|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-BE893F87-E7F6-56E5-BD27-328B532F8332" xml:lang="en"><title>Hello |
|
13 World Example: Using P.I.P.S.</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>This example application shows a simple EXE and DLL written using P.I.P.S. |
|
15 (P.I.P.S. Is POSIX on Symbian Platform). It also shows the dynamic lookup |
|
16 of symbols by name mechanism used in Unix-like operating systems, instead |
|
17 of the native Symbian Platform lookup by ordinal mechanism. P.I.P.S., from |
|
18 Symbian OS v9.3, provides APIs from <filepath>libdl</filepath> library to |
|
19 implement this lookup by name mechanism. </p> |
|
20 <p>The example defines a simple DLL using the P.I.P.S. <codeph>STDDLL</codeph> target |
|
21 type, with an exported function. It also creates a simple EXE, using the <codeph>STDEXE</codeph> target |
|
22 type, which calls the DLL's exported function using the lookup by name mechanism. |
|
23 These P.I.P.S. specific target types are required to enable the specific options |
|
24 for compilers and linkers to generate P.I.P.S. executables and to make symbol |
|
25 information available in the executable image. </p> |
|
26 <section><title>Download</title> <p>Click on the following link to download |
|
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> |
|
28 <section><title>Description</title> <p>The following sections provide more |
|
29 information about the example. </p> <p><b> Creating a simple DLL using P.I.P.S. |
|
30 STDDLL target type</b> </p> <p>The example creates a DLL file that declares |
|
31 and defines an exported function. The target type of this DLL file is <codeph>STDDLL</codeph>. |
|
32 It contains a header and a source file: </p> <ul> |
|
33 <li id="GUID-A0857840-AD8C-5313-A642-801A79382855"><p> <filepath>helloworlddllexample.h</filepath>: |
|
34 this declares a function with external linkage. Note that for a <codeph>STDDLL</codeph> library, |
|
35 functions and data with external linkage are exported by default, without |
|
36 any requirement for <codeph>IMPORT_C</codeph> and <codeph>EXPORT_C</codeph> declarations |
|
37 in header or source files. </p> </li> |
|
38 <li id="GUID-973CE8AE-5B87-5234-8145-20A6632E7F9C"><p> <filepath>helloworlddllexample.cpp</filepath>: |
|
39 this defines the function declared in the header file, which displays a hello |
|
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> |
|
49 <li id="GUID-0EC17FCA-7B6A-5FBF-8693-1C4BD629F553"><p> <xref href="GUID-312604D7-59D9-3C67-9D4F-42CFA24EAA2B.dita"><apiname>dlsysm()</apiname></xref>: |
|
50 This function gets the address of a symbol defined within the DLL loaded by |
|
51 the <codeph>dlopen()</codeph> call. </p> </li> |
|
52 </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>: |
|
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> |
|
57 <li id="GUID-B6003F4A-8919-5D15-844E-294A9020A2C2"><p> <xref href="GUID-F5B2CFAB-99F5-3A24-8F6C-ECAA61922FB0.dita"><apiname>dlerror()</apiname></xref>: |
|
58 This function is used to get the last error that occurred from 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> |
|
60 <section><title>Build</title> <p>The <xref href="GUID-3100800B-B2F7-50EF-BD4C-3C345ECCB2A5.dita">Symbian |
|
61 build process</xref> describes how to build this example application. </p> <p>The <filepath>HelloWorldExample</filepath> builds |
|
62 two files, a DLL file <filepath>helloworlddllexample.dll</filepath>, and an |
|
63 EXE file <filepath>helloworldexeexample.exe</filepath>, in the standard locations. </p> <p>To |
|
64 run the example, start <filepath>helloworldexeexample.exe</filepath> from |
|
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> |
|
68 </conbody></concept> |