<?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-E2B67F14-EC4E-41B6-9F8E-AB58B9E8D7B6" xml:lang="en"><title>extern

"C" and Symbian DEF files</title><shortdesc/><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>This article gives a general idea about the Symbian DEF file. Whenever

developers write any DLLs that export a set of APIs to the user, there will

be an entry for each exported API in the DEF file created. The developer will

use:</p>

<ul>

<li><p><codeph>IMPORT_C</codeph> while declaring exported APIs</p></li>

<li><p><codeph>EXPORT_C</codeph> while defining such APIs</p></li>

</ul>

<p>After building the application for the first time, it lists all the newly

exported APIs. After doing a freeze (for which the <cmdname>abld freeze winscw</cmdname> and <cmdname>abld

freeze armv5</cmdname> commands are used), the DEF files will be created under <filepath>BWINS</filepath> and <filepath>EABI</filepath> folders

within the project directory. These DEF files are used to create <filepath>.lib</filepath> files

for DLLs. In the DEF file, for each exported API, there will be mapping between

its prototype and a number will be present.  </p>

<p>Let's assume that directory structure used for implementing a library is

as shown below:</p>

<ul>

<li><p><filepath>LibraryName\group</filepath> -- <filepath>bld.inf</filepath> and <filepath>LibraryName.mmp</filepath> (all

build-related files)</p></li>

<li><p><filepath>LibraryName\inc</filepath> -- All project-specific headers

(user include headers)</p></li>

<li><p><filepath>LibraryName\src</filepath> -- All project-specific source

files </p></li>

</ul>

<p>If a developer is building the library for the first time, the developer

should follow these steps and give the following commands from <filepath>LibraryName\group</filepath>: </p>

<ol>

<li id="GUID-DE29CFD9-77C2-4790-89C6-5491F3EBA922"><p>Create the <filepath>abld.bat</filepath> file

for the project. </p><codeblock xml:space="preserve">LibraryName\group&gt;bldmake bldfiles</codeblock></li>

<li id="GUID-DC6AE0F4-64C6-432B-826B-26B7CDA8565C"><p>Build the project for

the default platform (which will be <codeph>WINSCW</codeph> and <codeph>ARMV5</codeph>). </p><codeblock xml:space="preserve">LibraryName\group&gt;abld build</codeblock></li>

<li id="GUID-836865DB-F613-4000-95AC-DDC9E3F498B2"><p>Create the DEF file

for the default platform (<filepath>LibraryName\BWINS\LibraryNameu.def and

LibraryName\EABI\LibraryNameu.def</filepath>). </p><codeblock xml:space="preserve">LibraryName\group&gt;abld freeze</codeblock></li>

<li id="GUID-C69111BA-1568-4CB4-8AB5-0EDEFC854D39"><p>Create <filepath>.lib</filepath> files

for the DLL using DEF file entries. (<filepath>LibraryName.lib</filepath>) </p><codeblock xml:space="preserve">LibraryName\group&gt; abld build</codeblock></li>

</ol>

<p>The final step is required since applications that link with this library

(<filepath>LibraryName.DLL</filepath>) will link with <filepath>LibraryName.lib</filepath> during

link time. If the developer fails to perform the final step, the application

will get a linker error because there is no <filepath>LibraryName.lib</filepath> present.</p>

<section id="GUID-3AD1D783-C36F-4443-8957-6DB9434927B5">       <title>Rule

for using extern "C"</title>       <p>When porting or writing libraries that

export C APIs to the user, care should be taken to ensure that extern "C"

is used properly if those APIs are implemented in a C++ source file. Otherwise

these libraries may either not be built for the target platform (ARMV5) or

the user of such library will get a linker error when using exported APIs

of such library.  </p><p>If extern "C" is declared in the header and not defined

in the source, then after building the library there will be a similar entry

in DEF files. The compiler will not give external linkage to these APIs. This

can be observed when trying to use these APIs from some other C source file.

To overcome this, extern "C" must be present in both declarations and definitions.</p><p><b>Example

code</b></p><codeblock xml:space="preserve">/*File: SampleDLL.h*/

/*extern "C" is not used for declaration!*/ 

#ifndef SAMPLEDLL_H

#define SAMPLEDLL_H

typedef int MyInt;

typedef int (*MyFunPtr) ();

IMPORT_C int MyLibLibFun1(MyInt aParam);

IMPORT_C int MyLibLibFun3(MyFunPtr);

IMPORT_C int MyLibLibFun2(int (*MyFun1)());

#endif /*SAMPLEDLL_H*/

//File: SampleDLL.cpp

#include "SampleDLL.h"

// extern "C" is used for definition

extern "C"  {

EXPORT_C int MyLibLibFun1(MyInt aParam)

   {

   return aParam + 10;

   }

EXPORT_C int MyLibLibFun2(int (*MyFun1)())

   {

   return MyFun1();

   }

EXPORT_C int MyLibLibFun3(MyFunPtr aPtr)

   {

   return aPtr();

   }

}

</codeblock><p><b>Building for <codeph>WINSCW</codeph></b></p><p>This code

will get compiled for <codeph>WINSCW</codeph>. The DEF file for <codeph>WINSCW</codeph> will

have the following entries:</p><codeblock xml:space="preserve">EXPORTS

     ?MyLibLibFun1@@YAHH@Z @ 1 NONAME ; int MyLibLibFun1(int)

     ?MyLibLibFun2@@YAHP6AHXZ@Z @ 2 NONAME ; int MyLibLibFun2(int (*)(void))

     ?MyLibLibFun3@@YAHP6AHXZ@Z @ 3 NONAME ; int MyLibLibFun3(int (*)(void)) </codeblock><p>If

the user comments extern "C" from the above <filepath>SampleDLL.cpp</filepath> file,

the DEF file entries will be the same.</p><p><b>Building for <codeph>ARMv5</codeph></b></p><p>If

the user try's the above code without extern "C" in <filepath>SampleDLL.cpp</filepath>,

the code will get built and the DEF file entry for <codeph>ARMv5</codeph> will

be:</p><codeblock xml:space="preserve">EXPORTS

     _Z12MyLibLibFun1i @ 1 NONAME

     _Z12MyLibLibFun2PFivE @ 2 NONAME

     _Z12MyLibLibFun3PFivE @ 3 NONAME  </codeblock><p>If the user keeps the

extern "C" in <filepath>SampleDLL.cpp</filepath>, this code will not get compiled

for <codeph>ARMv5</codeph> and will result in the error given below:  </p><codeblock xml:space="preserve">"..\src\Sampledll.cpp", line 7: Error:  #337: linkage specification is incompatible with previous "MyLibLibFun1" (declared at line 9 of "..\inc\SampleDLL.h")

   EXPORT_C int MyLibLibFun1(MyInt aParam)

                ^ 

"..\src\Sampledll.cpp", line 17: Error:  #337: linkage specification is incompatible with previous "MyLibLibFun3" (declared at line 11 of "..\inc\SampleDLL.h")

   EXPORT_C int MyLibLibFun3(MyFunPtr aPtr)

               ^</codeblock><p>The reason for the errors is that <codeph>MyLibLibFun1</codeph> and <codeph>MyLibLibFun3</codeph> use <codeph>typedef</codeph> datatypes. There is no issue with <codeph>MyLibLibFun2()</codeph> since

it does not use <codeph>typedef</codeph> datatypes. To overcome these errors,

the user must keep both the declaration and the definition within extern "C"

linkage.</p><codeblock xml:space="preserve">/*File: SampleDLL.h*/    

#ifndef SAMPLEDLL_H  

#define SAMPLEDLL_H  

/*extern "C" is used for declaration also*/

typedef int MyInt;  

typedef int (*MyFunPtr) ();    

#ifdef __cplusplus  

extern "C" {  

#endif //__cplusplus    

IMPORT_C int MyLibLibFun1(MyInt aParam);  

IMPORT_C int MyLibLibFun3(MyFunPtr);  

IMPORT_C int MyLibLibFun2(int (*MyFun1)());    

#ifdef __cplusplus  

}  

#endif //__cplusplus    

#endif /*SAMPLEDLL_H*/ </codeblock><p>When everything is within extern "C"

(extern "C" in header and implementation), the DEF file for <codeph>ARMv5</codeph> and <codeph>WINSCW</codeph> looks

as follows:</p><codeblock xml:space="preserve">EXPORTS

    MyLibLibFun1 @ 1 NONAME

    MyLibLibFun2 @ 2 NONAME

    MyLibLibFun3 @ 3 NONAME </codeblock><p>So, as one can observe in the above

section where different DEF file entries are created with and without extern

"C", the user must make sure that the rule is followed. extern "C" has to

be used in both declaration and definition: otherwise the user will either,

not be able to build it for all the platforms or, it will not be possible

to use those exported C APIs in other applications. </p>     </section>

</conbody></concept>