<?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-457628C5-2972-4432-A03F-CD8CC0E1B60A" xml:lang="en"><title>Initializing

a Library</title><shortdesc>Sometimes, a library needs to be initialized before it can provide

any services to client of the library. This can be done in several ways. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-A4E1C734-DF38-4AA7-8FDB-4FF97706F005">       <title>Export

functions for initializing and closing the library</title>       <p>The library

can export more than one function for initializing and closing the library.</p><p>The

client of the library calls the initialization function before requesting

any services and calls close when the client does not use the library. </p><p><b>Example:</b></p><p>There

is a DLL called <filepath>xxx.dll</filepath>. Two functions <codeph>InitXXX()</codeph> and <codeph>CloseXXX()</codeph> are

exported from this DLL. The library code can look like the following:</p><p>Library

header file <filepath>xxx_init.h</filepath>:</p><codeblock xml:space="preserve">....

IMPORT_C void InitXXX();

IMPORT_C CloseXXX();

....

</codeblock><p>Library source file <filepath>xxx_init.cpp</filepath>:</p><codeblock xml:space="preserve">static int _InitCount = 0;

EXPORT_C void InitXXX()

{

   if(_InitCount++ <= 0)

   {

   // initialize xxx.dll

   }

}

EXPORT_C CloseXXX()

{

   if(--_InitCount <= 0)

   {

   // free all the resources

   }

}

</codeblock><p>User code looks like the following:</p><codeblock xml:space="preserve">#include &lt;xxx_init.h&gt;

...

int main()

{

   InitXXX();

   ....

   ....

   CloseXXX();

   return 0;

}

</codeblock>     </section>

<section id="GUID-ADE950F6-8C93-4080-86A1-91C5F92D254D"><title>Exported functions

check whether the library is initialized</title><p>Every exported function

can check whether the library has been initialized. The library can export

one function (for example, <codeph>CloseLib()</codeph>) and this can be called

before exiting <codeph>main()</codeph>.</p><p><b>Example:</b></p><p>Library

header file <filepath>xxx.h</filepath>: </p><codeblock xml:space="preserve">....

IMPORT_C void X_Export_Api1();

IMPORT_C void X_Export_Api2();

....

</codeblock><p>Library source file <filepath>xxx.cpp</filepath>: </p><codeblock xml:space="preserve">static int _InitCount = 0;

#define INIT_LIB if(_InitCount == 0) \

           {\

               _InitCount++; \

               InitXXX(); \

           }

LOCAL_C void InitXXX()

{

   // initialize xxx.dll

}

LOCAL_C CloseXXX()

{

   // free all the resources

}

EXPORT_C void X_Export_Api1()

{

   INIT_LIB;

   ...

   ...

}

</codeblock><p>User code looks like the following:</p><codeblock xml:space="preserve">#include &lt;xxx.h&gt;

...

int main()

{

   ....

   ....

   X_Export_Api1();

   ....

   ....

   X_Export_Api2();

   ....

   ....

   return 0;

}

</codeblock></section>

<section id="GUID-F387926E-A6D2-439C-9EEA-A3751E38DFBE"><title>Library defines

a static object</title><p>The library can define static objects and call the

initialization code from the constructor of these static objects so that before

calling, the application entry point library will be initialized.</p><p><b>Example:</b></p><p>Library

header file <filepath>xxx.h</filepath>: </p><codeblock xml:space="preserve">....

IMPORT_C void X_Export_Api1();

IMPORT_C void X_Export_Api2();

....</codeblock><p>Library source file <filepath>xxx.cpp</filepath>: </p><codeblock xml:space="preserve">LOCAL_C void InitXXX()

{

   // initialize xxx.dll

}

LOCAL_C CloseXXX()

{

   // free all the resources

}

class LibInit

{

   LibInit();

   ~LibInit();

};

LibInit::LibInit()

{

   // put all library initialization code here.

   InitXXX();

}

LibInit::~LibInit()

{

   // free all resources

   CloseXXX();

}

static LibInit _libInit;

</codeblock><p>User code looks like the following:</p><codeblock xml:space="preserve">#include &lt;xxx.h&gt;

int main()

{

   ....

   ....

   X_Export_Api1();

   ....

   ....

   X_Export_Api2();

   ....

   ....

   return 0;

}

</codeblock></section>