<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<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>

<p>This example application shows a simple EXE and DLL written using P.I.P.S.

(P.I.P.S. Is POSIX on Symbian Platform). It also shows the dynamic lookup

of symbols by name mechanism used in Unix-like operating systems, instead

of the native Symbian Platform lookup by ordinal 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>

<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 EXE, using the <codeph>STDEXE</codeph> target

type, which calls the DLL's exported function using the lookup by name mechanism.

These P.I.P.S. specific target types are required to enable the specific options

for compilers and linkers to generate P.I.P.S. executables and to make symbol

information available in the executable image. </p>

<section><title>Download</title> <p>Click on the following link to 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>

<section><title>Description</title> <p>The following sections provide more

information about the example. </p> <p><b> Creating a simple DLL using P.I.P.S.

STDDLL target type</b> </p> <p>The example creates a DLL file that declares

and defines an exported function. The target type of this DLL file is <codeph>STDDLL</codeph>.

It contains a header and a source file: </p> <ul>

<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 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>

<li id="GUID-973CE8AE-5B87-5234-8145-20A6632E7F9C"><p> <filepath>helloworlddllexample.cpp</filepath>:

this defines the function declared in the header file, which displays a hello

world message to the console. </p> </li>

</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 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>

<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 function. </p> </li>

</ul> <ul>

<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 loaded by

the <codeph>dlopen()</codeph> call. </p> </li>

</ul> <ul>

<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>

</ul> <ul>

<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 any of the <filepath>libdl</filepath> APIs. </p> </li>

</ul> <p>The EXE links to <filepath>libdl.lib</filepath> to use these functions. </p> </section>

<section><title>Build</title> <p>The <xref href="GUID-3100800B-B2F7-50EF-BD4C-3C345ECCB2A5.dita">Symbian

build process</xref> describes how to build this example application. </p> <p>The <filepath>HelloWorldExample</filepath> builds

two files, a DLL file <filepath>helloworlddllexample.dll</filepath>, and an

EXE file <filepath>helloworldexeexample.exe</filepath>, in the standard locations. </p> <p>To

run the example, start <filepath>helloworldexeexample.exe</filepath> from

the file system or from your IDE. After launching the executable, depending

on the emulator you are using, you may need to navigate away from the application

launcher or shell screen to view the console. </p> </section>