7 Nokia Corporation - initial contribution. |
7 Nokia Corporation - initial contribution. |
8 Contributors: |
8 Contributors: |
9 --> |
9 --> |
10 <!DOCTYPE concept |
10 <!DOCTYPE concept |
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
12 <concept id="GUID-BE893F87-E7F6-56E5-BD27-328B532F8332" xml:lang="en"><title>Hello |
12 <concept id="GUID-BE893F87-E7F6-56E5-BD27-328B532F8332" xml:lang="en"><title>Hello World Example: Using P.I.P.S.</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
13 World Example: Using P.I.P.S.</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
13 <p>This example application shows a simple EXE and DLL written using |
14 <p>This example application shows a simple EXE and DLL written using P.I.P.S. |
14 P.I.P.S. (P.I.P.S. Is POSIX on Symbian Platform). It also shows the |
15 (P.I.P.S. Is POSIX on Symbian Platform). It also shows the dynamic lookup |
15 dynamic lookup of symbols by name mechanism used in Unix-like operating |
16 of symbols by name mechanism used in Unix-like operating systems, instead |
16 systems, instead of the native Symbian Platform lookup by ordinal |
17 of the native Symbian Platform lookup by ordinal mechanism. P.I.P.S., from |
17 mechanism. P.I.P.S., from Symbian OS v9.3, provides APIs from <filepath>libdl</filepath> library to implement this lookup by name mechanism. </p> |
18 Symbian OS v9.3, provides APIs from <filepath>libdl</filepath> library to |
18 <p>The example defines a simple DLL using the P.I.P.S. <codeph>STDDLL</codeph> target type, with an exported function. It also creates a simple |
19 implement this lookup by name mechanism. </p> |
19 EXE, using the <codeph>STDEXE</codeph> target type, which calls the |
20 <p>The example defines a simple DLL using the P.I.P.S. <codeph>STDDLL</codeph> target |
20 DLL's exported function using the lookup by name mechanism. These |
21 type, with an exported function. It also creates a simple EXE, using the <codeph>STDEXE</codeph> target |
21 P.I.P.S. specific target types are required to enable the specific |
22 type, which calls the DLL's exported function using the lookup by name mechanism. |
22 options for compilers and linkers to generate P.I.P.S. executables |
23 These P.I.P.S. specific target types are required to enable the specific options |
23 and to make symbol information available in the executable image. </p> |
24 for compilers and linkers to generate P.I.P.S. executables and to make symbol |
24 <section id="GUID-F39633E1-9E29-45BA-9F11-66E011B16687"><title>Download</title> <p>Click on the following link to |
25 information available in the executable image. </p> |
25 download the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-42af5ea2-87c6-46ef-b872-af35876c73c7.zip" scope="external">HelloWorldExample.zip</xref></p><p>Click: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-42af5ea2-87c6-46ef-b872-af35876c73c7.html" scope="peer">browse</xref> to view the example code. </p> </section> |
26 <section><title>Download</title> <p>Click on the following link to download |
26 <section id="GUID-459D68E3-EC28-4F21-858A-10678A443EEE"><title>Description</title> <p>The following sections provide |
27 the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-42af5ea2-87c6-46ef-b872-af35876c73c7.zip" scope="external">HelloWorldExample.zip</xref></p><p>Click: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-42af5ea2-87c6-46ef-b872-af35876c73c7.html" scope="peer">browse</xref> to view the example code. </p> </section> |
27 more information about the example. </p> <p><b> Creating a simple |
28 <section><title>Description</title> <p>The following sections provide more |
28 DLL using P.I.P.S. STDDLL target type</b> </p> <p>The example creates |
29 information about the example. </p> <p><b> Creating a simple DLL using P.I.P.S. |
29 a DLL file that declares and defines an exported function. The target |
30 STDDLL target type</b> </p> <p>The example creates a DLL file that declares |
30 type of this DLL file is <codeph>STDDLL</codeph>. It contains a header |
31 and defines an exported function. The target type of this DLL file is <codeph>STDDLL</codeph>. |
31 and a source file: </p> <ul> |
32 It contains a header and a source file: </p> <ul> |
32 <li id="GUID-A0857840-AD8C-5313-A642-801A79382855"><p> <filepath>helloworlddllexample.h</filepath>: this declares a function with external linkage. Note that for a <codeph>STDDLL</codeph> library, functions and data with external linkage |
33 <li id="GUID-A0857840-AD8C-5313-A642-801A79382855"><p> <filepath>helloworlddllexample.h</filepath>: |
33 are exported by default, without any requirement for <codeph>IMPORT_C</codeph> and <codeph>EXPORT_C</codeph> declarations in header or source files. </p> </li> |
34 this declares a function with external linkage. Note that for a <codeph>STDDLL</codeph> library, |
34 <li id="GUID-973CE8AE-5B87-5234-8145-20A6632E7F9C"><p> <filepath>helloworlddllexample.cpp</filepath>: this defines the function declared in the header file, which displays |
35 functions and data with external linkage are exported by default, without |
35 a hello world message to the console. </p> </li> |
36 any requirement for <codeph>IMPORT_C</codeph> and <codeph>EXPORT_C</codeph> declarations |
36 </ul> <p><b> Creating a simple EXE using P.I.P.S. STDEXE target type</b> </p> <p>The example creates an EXE file which calls the exported |
37 in header or source files. </p> </li> |
37 function of the loaded DLL. The target type of this EXE file is <codeph>STDEXE</codeph>. It calls the following <filepath>libdl</filepath> functions to use the lookup by name mechanism: </p> <ul> |
38 <li id="GUID-973CE8AE-5B87-5234-8145-20A6632E7F9C"><p> <filepath>helloworlddllexample.cpp</filepath>: |
38 <li id="GUID-08422DA9-EE4F-502C-8D31-EB19BC86F98B"><p> <xref href="GUID-51FB35C0-CFC2-357A-8ACA-FE7480C53AD3.dita"><apiname>dlopen()</apiname></xref>: This function is used to load the DLL file which contains an exported |
39 this defines the function declared in the header file, which displays a hello |
39 function. </p> </li> |
40 world message to the console. </p> </li> |
|
41 </ul> <p><b> Creating a simple EXE using P.I.P.S. STDEXE target type</b> </p> <p>The |
|
42 example creates an EXE file which calls the exported function of the loaded |
|
43 DLL. The target type of this EXE file is <codeph>STDEXE</codeph>. It calls |
|
44 the following <filepath>libdl</filepath> functions to use the lookup by name |
|
45 mechanism: </p> <ul> |
|
46 <li id="GUID-08422DA9-EE4F-502C-8D31-EB19BC86F98B"><p> <xref href="GUID-51FB35C0-CFC2-357A-8ACA-FE7480C53AD3.dita"><apiname>dlopen()</apiname></xref>: |
|
47 This function is used to load the DLL file which contains an exported function. </p> </li> |
|
48 </ul> <ul> |
40 </ul> <ul> |
49 <li id="GUID-0EC17FCA-7B6A-5FBF-8693-1C4BD629F553"><p> <xref href="GUID-312604D7-59D9-3C67-9D4F-42CFA24EAA2B.dita"><apiname>dlsysm()</apiname></xref>: |
41 <li id="GUID-0EC17FCA-7B6A-5FBF-8693-1C4BD629F553"><p> <xref href="GUID-312604D7-59D9-3C67-9D4F-42CFA24EAA2B.dita"><apiname>dlsysm()</apiname></xref>: This function gets the address of a symbol defined within the DLL |
50 This function gets the address of a symbol defined within the DLL loaded by |
42 loaded by the <codeph>dlopen()</codeph> call. </p> </li> |
51 the <codeph>dlopen()</codeph> call. </p> </li> |
|
52 </ul> <ul> |
43 </ul> <ul> |
53 <li id="GUID-EFC5BA53-F378-5D2B-A550-1055DA8CBAD7"><p> <xref href="GUID-F74DC7CB-1E3F-368E-99A7-DD4B38FF7EF0.dita"><apiname>dlclose()</apiname></xref>: |
44 <li id="GUID-EFC5BA53-F378-5D2B-A550-1055DA8CBAD7"><p> <xref href="GUID-F74DC7CB-1E3F-368E-99A7-DD4B38FF7EF0.dita"><apiname>dlclose()</apiname></xref>: This function informs the system that the DLL loaded by a previous <codeph>dlopen()</codeph> call is no longer needed by the application. </p> </li> |
54 This function informs the system that the DLL loaded by a previous <codeph>dlopen()</codeph> call |
|
55 is no longer needed by the application. </p> </li> |
|
56 </ul> <ul> |
45 </ul> <ul> |
57 <li id="GUID-B6003F4A-8919-5D15-844E-294A9020A2C2"><p> <xref href="GUID-F5B2CFAB-99F5-3A24-8F6C-ECAA61922FB0.dita"><apiname>dlerror()</apiname></xref>: |
46 <li id="GUID-B6003F4A-8919-5D15-844E-294A9020A2C2"><p> <xref href="GUID-F5B2CFAB-99F5-3A24-8F6C-ECAA61922FB0.dita"><apiname>dlerror()</apiname></xref>: This function is used to get the last error that occurred from |
58 This function is used to get the last error that occurred from any of the <filepath>libdl</filepath> APIs. </p> </li> |
47 any of the <filepath>libdl</filepath> APIs. </p> </li> |
59 </ul> <p>The EXE links to <filepath>libdl.lib</filepath> to use these functions. </p> </section> |
48 </ul> <p>The EXE links to <filepath>libdl.lib</filepath> to use these |
60 <section><title>Build</title> <p>The <xref href="GUID-3100800B-B2F7-50EF-BD4C-3C345ECCB2A5.dita">Symbian |
49 functions. </p> </section> |
61 build process</xref> describes how to build this example application. </p> <p>The <filepath>HelloWorldExample</filepath> builds |
50 <section id="GUID-15EDF774-BC24-4BD5-A185-697DCFDCF732"><title>Build</title> <p>The <filepath>HelloWorldExample</filepath> builds two files, a DLL file <filepath>helloworlddllexample.dll</filepath>, and an EXE file <filepath>helloworldexeexample.exe</filepath>, |
62 two files, a DLL file <filepath>helloworlddllexample.dll</filepath>, and an |
51 in the standard locations. </p> <p>To run the example, start <filepath>helloworldexeexample.exe</filepath> from the file system or from |
63 EXE file <filepath>helloworldexeexample.exe</filepath>, in the standard locations. </p> <p>To |
52 your IDE. After launching the executable, depending on the emulator |
64 run the example, start <filepath>helloworldexeexample.exe</filepath> from |
53 you are using, you may need to navigate away from the application |
65 the file system or from your IDE. After launching the executable, depending |
|
66 on the emulator you are using, you may need to navigate away from the application |
|
67 launcher or shell screen to view the console. </p> </section> |
54 launcher or shell screen to view the console. </p> </section> |
68 </conbody></concept> |
55 </conbody></concept> |