|
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-457628C5-2972-4432-A03F-CD8CC0E1B60A" xml:lang="en"><title>Initializing |
|
13 a Library</title><shortdesc>Sometimes, a library needs to be initialized before it can provide |
|
14 any services to client of the library. This can be done in several ways. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
15 <section id="GUID-A4E1C734-DF38-4AA7-8FDB-4FF97706F005"> <title>Export |
|
16 functions for initializing and closing the library</title> <p>The library |
|
17 can export more than one function for initializing and closing the library.</p><p>The |
|
18 client of the library calls the initialization function before requesting |
|
19 any services and calls close when the client does not use the library. </p><p><b>Example:</b></p><p>There |
|
20 is a DLL called <filepath>xxx.dll</filepath>. Two functions <codeph>InitXXX()</codeph> and <codeph>CloseXXX()</codeph> are |
|
21 exported from this DLL. The library code can look like the following:</p><p>Library |
|
22 header file <filepath>xxx_init.h</filepath>:</p><codeblock xml:space="preserve">.... |
|
23 IMPORT_C void InitXXX(); |
|
24 IMPORT_C CloseXXX(); |
|
25 .... |
|
26 </codeblock><p>Library source file <filepath>xxx_init.cpp</filepath>:</p><codeblock xml:space="preserve">static int _InitCount = 0; |
|
27 EXPORT_C void InitXXX() |
|
28 { |
|
29 if(_InitCount++ <= 0) |
|
30 { |
|
31 // initialize xxx.dll |
|
32 } |
|
33 } |
|
34 EXPORT_C CloseXXX() |
|
35 { |
|
36 if(--_InitCount <= 0) |
|
37 { |
|
38 // free all the resources |
|
39 } |
|
40 } |
|
41 </codeblock><p>User code looks like the following:</p><codeblock xml:space="preserve">#include <xxx_init.h> |
|
42 ... |
|
43 int main() |
|
44 { |
|
45 InitXXX(); |
|
46 .... |
|
47 .... |
|
48 CloseXXX(); |
|
49 return 0; |
|
50 } |
|
51 </codeblock> </section> |
|
52 <section id="GUID-ADE950F6-8C93-4080-86A1-91C5F92D254D"><title>Exported functions |
|
53 check whether the library is initialized</title><p>Every exported function |
|
54 can check whether the library has been initialized. The library can export |
|
55 one function (for example, <codeph>CloseLib()</codeph>) and this can be called |
|
56 before exiting <codeph>main()</codeph>.</p><p><b>Example:</b></p><p>Library |
|
57 header file <filepath>xxx.h</filepath>: </p><codeblock xml:space="preserve">.... |
|
58 IMPORT_C void X_Export_Api1(); |
|
59 IMPORT_C void X_Export_Api2(); |
|
60 .... |
|
61 </codeblock><p>Library source file <filepath>xxx.cpp</filepath>: </p><codeblock xml:space="preserve">static int _InitCount = 0; |
|
62 #define INIT_LIB if(_InitCount == 0) \ |
|
63 {\ |
|
64 _InitCount++; \ |
|
65 InitXXX(); \ |
|
66 } |
|
67 LOCAL_C void InitXXX() |
|
68 { |
|
69 // initialize xxx.dll |
|
70 } |
|
71 LOCAL_C CloseXXX() |
|
72 { |
|
73 // free all the resources |
|
74 } |
|
75 EXPORT_C void X_Export_Api1() |
|
76 { |
|
77 INIT_LIB; |
|
78 ... |
|
79 ... |
|
80 } |
|
81 </codeblock><p>User code looks like the following:</p><codeblock xml:space="preserve">#include <xxx.h> |
|
82 ... |
|
83 int main() |
|
84 { |
|
85 .... |
|
86 .... |
|
87 X_Export_Api1(); |
|
88 .... |
|
89 .... |
|
90 X_Export_Api2(); |
|
91 .... |
|
92 .... |
|
93 return 0; |
|
94 } |
|
95 </codeblock></section> |
|
96 <section id="GUID-F387926E-A6D2-439C-9EEA-A3751E38DFBE"><title>Library defines |
|
97 a static object</title><p>The library can define static objects and call the |
|
98 initialization code from the constructor of these static objects so that before |
|
99 calling, the application entry point library will be initialized.</p><p><b>Example:</b></p><p>Library |
|
100 header file <filepath>xxx.h</filepath>: </p><codeblock xml:space="preserve">.... |
|
101 IMPORT_C void X_Export_Api1(); |
|
102 IMPORT_C void X_Export_Api2(); |
|
103 ....</codeblock><p>Library source file <filepath>xxx.cpp</filepath>: </p><codeblock xml:space="preserve">LOCAL_C void InitXXX() |
|
104 { |
|
105 // initialize xxx.dll |
|
106 } |
|
107 LOCAL_C CloseXXX() |
|
108 { |
|
109 // free all the resources |
|
110 } |
|
111 class LibInit |
|
112 { |
|
113 LibInit(); |
|
114 ~LibInit(); |
|
115 }; |
|
116 LibInit::LibInit() |
|
117 { |
|
118 // put all library initialization code here. |
|
119 InitXXX(); |
|
120 } |
|
121 LibInit::~LibInit() |
|
122 { |
|
123 // free all resources |
|
124 CloseXXX(); |
|
125 } |
|
126 static LibInit _libInit; |
|
127 </codeblock><p>User code looks like the following:</p><codeblock xml:space="preserve">#include <xxx.h> |
|
128 int main() |
|
129 { |
|
130 .... |
|
131 .... |
|
132 X_Export_Api1(); |
|
133 .... |
|
134 .... |
|
135 X_Export_Api2(); |
|
136 .... |
|
137 .... |
|
138 return 0; |
|
139 } |
|
140 </codeblock></section> |
|
141 </conbody></concept> |