The Ultimate (DLL) Header File

原创 2002年03月17日 13:43:00


Efficient and appropriate use of header files requires a few tricks. If you simply define a set of functions, everything works fine. No problems. If the file is included more than once because of a complex #include chain, you get redundant declarations. Most compilers, including the Microsoft C/C++ compilers, simply ignore these redundant function and variable declarations. However, if there are any class, typedef, struct, or some other declarations, the compiler will complain bitterly if they are seen twice, claiming they are duplication declarations. It does not choose to see if the structures actually are identical. So there is an idiom to avoid duplication declarations, which is to put the entire contents of the header file in an #ifndef, skipping the body if a symbol defined within the body is already defined. This works acceptably well for short files, but is a performance disaster for lengthy files, since each line of the file must be read. For standard header files, precompiled headers work well in eliminating this problem, but it is harder to justify putting your own headers into a precompiled header file since the effects of a simple change result in a massive recompilation (stdafx.h has to be recompiled). Microsoft has added a #pragma that means the header file is read only once. All of this is shown in detail below.

DLL Headers: Additional Complexity

When constructing a DLL, you need a header file to interface to it. However, the obvious solutions do not work as expected. For example, if you declare a function in a fashion so as to export it, you need to add __declspec(dllexport) to its declaration, and if you don't want name mangling, particularly important if you expect to use the DLL with straight C code as well as C++, you need to define it in the .cpp file as

extern "C" __declspec(dllexport) function-header
    // ... whatever

The problem with this approach is that the obvious solutions to the header file don't work.

The First Wrong Approach

The first attempt you might make is to declare, in the .h file

extern "C" function-prototype; // incorrect

This doesn't work because the compiler will complain that the prototype is incompatible with the declaration. What causes this is the prototype lacks the __declspec(dllexport) declaration. So, you say, I'll just add that in. So you get

extern "C" __declspec(dllexport) function-prototype; // incorrect

This doesn't work for a different reason. Although you will no longer get a warning when you compile the DLL, you will get a warning when you compile the application, because the declaration __declspec(dllexport) is incompatible with the use of the function call.

The Second Wrong Approach

At this point a couple workarounds present themselves. The first one you might consider is to use two header files, one of which has the __declspec(dllexport), and the other of which does not. This is a Bad Idea. The reason is that you lose the consistency checking you would get if you include the same header file into both the DLL compilation and the client compilation. For example, if you change the function to have a different parameter type, the compiler will complain unless you change the DLL's header file prototypes to correspond. But in this case, the DLL header file is completely useless, and might as well not exist, because there is a completely separate header file for the client. It remains uncorrected, and there is no cross-check against the actual module. You lose.

A workable but inconvenient approach

At this point, you could remove the __declspec(dllexport) declarations entirely. This means your one-and-only header file will be consistent with the source, but, whoops, the symbols are not exported. To get around this, you can add either the /exports:function command line switch to the linker command line, or use a .def file and add the function name to the EXPORTS section. This is a valid, correct solution, and it works, but you will find that it quickly becomes inconvenient, because you have to remember to add the function name declaration to the /exports switch or add the name to the .def file. Anyone who did DLLs or Windows programming in Win16 in the days before the __export keyword was added to that language will remember how bad this was. Those of you who did not, take our word for it, it was a real royal pain to deal with this. So I'm disinclined to use this solution unless there are other compelling reasons, which there rarely are.

The Ultimate Header File

This is a model which I have cut-and-pasted many times for every DLL I've built in recent years. I've added some comments to help explain and show visually what is going on, and you will probably want to remove these before actually using it.

The uniquename name is something of your own choice. It could be a simple text string, e.g., _DEFINED_MYDLL_HEADER, or you could use GUIDGEN to create a GUID. If you use GUIDGEN, create a "Registry Entry" format, which is 


Remove the { }s  and replace the hyphens with underscores. This would give you a symbol like


which guarantees that you will never, ever have a conflict with any other header file.

#ifndef _DEFINED_uniqueheadername  //---------------1---------------+
#define _DEFINED_uniqueheadername  //---------------1---------------+
                                                                 // |
  #if _MSC_VER > 1000  //--------------2---------------+            |
    #pragma once                                    // |            |
  #endif //----------------------------2---------------+            |
                                                                 // |
  #ifdef __cplusplus  //---------------3---------------+            |
  extern "C" {                                      // |            |
  #endif // __cplusplus  //------------3---------------+            |
                                                                 // |
  #ifdef _COMPILING_uniqueheadername  //-----------4-----------+    |
    #define LIBSPEC __declspec(dllexport)                   // |    |
  #else                                                     // |    |
    #define LIBSPEC __declspec(dllimport)                   // |    |
  #endif // _COMPILING_uniqueheadername  //--------4-----------+    |
                                                            // |    |
  LIBSPEC linkagetype resulttype name(parameters);          // |    |
  // ... more declarations as needed                        // |    |
  #undef LIBSPEC   //------------------------------4-----------+    |
                                                                 // |
  #ifdef __cplusplus    //----------------5---------------+         |
  }                                                    // |         |
  #endif // __cplusplus  //---------------5---------------+         |
#endif // _DEFINED_uniqueheadername //-----------------1------------+

The explanation of the "contour lines" is as follows

  1. If the header file is actually processed, this is the traditional C idiom to keep it from being processed twice. The first time the file is included, the symbol _DEFINED_uniqueheadername is not defined, so the file is processed. The first thing it does is declare that symbol, so that in subsequent inclusions, the entire body of the file is skipped.
  2. This is a #pragma which is defined only for C compilers version 10.00 and later (note that the C compiler version and the VC++ version are not related numbers). If this #pragma is implemented, the inclusion of this file in a compilation creates an entry in an "included files table" for that compilation. Subsequent attempts to include this file in the same compilation first check this table, and if the filename is the same, the compiler doesn't even bother to open the file. However, you can't eliminate the contour 1 test, because this #pragma, for reasons best known only to its implementor, is case sensitive in the file name, even though the file name of the underlying operating system is case insensitive. It seems utterly silly that we should have two discrete behaviors, but since when has rationality and common sense affected what some programmers do?
  3. This contour is required to make the header file compatible with both C and C++. It assumes that you want C compatibility, and therefore that the function names should not have C++ "name mangling" applied. The downside of this is that you lose the ability to overload functions based on parameter types. If you are doing a C++-only DLL, you would not use this contour, and you would also eliminate contour 5. The __cplusplus symbol is defined for a C++ compilation but undefined for a C compilation.
  4. This is a funny contour. The #if/#else/#endif contour decides which form of __declspec to use for the declaration. The scope of the effect of this contour actually projects beyond the conditional and extends to the #undef, during which the symbol LIBSPEC is defined. Strictly speaking, you do not need to do the __declspec(dllimport); you could just define LIBSPEC as an empty macro. However, declaring __declspec(dllimport) does same one or two instructions on the linkage when it is finally resolved. Since, using this method, it costs nothing to add this slight efficiency, why not? Note that contour 4 is not needed for non-DLL files.
  5. This is the matching close brace to the structure created in contour 3. If you are doing a C++-only DLL, you would eliminate this as well as contour 3. 

Now, in the DLL itself, you have to do one thing: you must declare the _COMPILING_uniquename symbol before the #include. After that, you simply declare the function as shown.

#include "stdafx.h" // usually 
#define _COMPILING_uniquename
#include "myDLL.h"

extern "C" __declspec(dllexport) linkagetype resulttype name(parameters)
     // ... whatever

and you will not get any compiler conflicts. This will use the same header file for both the DLL and client, and all the Right Things will happen.

Oracle使用Linux nfs方式挂载备份文件后访问出错The file header is corrupted

从远端备份服务器NFS挂载备份目录至本机时,执行oracle rman 'catalog start with'命令,提示部分文件头损坏,如下: [root@lkdb bak0524]# df -h ...
  • lk_db
  • lk_db
  • 2016年05月24日 16:30
  • 555

data file header的一点点研究

数据文件头就是datafile 的第1,第2个block,我们直接通过alter system dump datafile n block min 1 max 2;是得不到任何信息的,请看测试:SQL...
  • robinson1988
  • robinson1988
  • 2009年12月25日 12:41
  • 3925

Android Studio Modify File Header

Some times we need to modify file header as to add more detail or styled info in each class or file ...
  • ysmintor
  • ysmintor
  • 2017年04月06日 10:29
  • 762

遇到Debug/XXX.pch is not a precompiled header file的问题

在编译时遇到'Debug/XXX.pch' is not a precompiled header file created with this compiler  Error executing x...
  • ClaireShi
  • ClaireShi
  • 2014年01月08日 10:35
  • 3369

解决 Cannot open precompiled header file: 'Debug/****.pch'

  • cyxcw1
  • cyxcw1
  • 2013年10月08日 21:24
  • 8982

C++ Header file

“自古穷通皆有定”转一篇文章,以备查用。c++header file#include //设定插入点 #include //字符处理 #include //定义错误码 #include //浮...
  • zhaohuiy
  • zhaohuiy
  • 2009年10月16日 19:39
  • 942

VC编译程序时Cannot open precompiled header file: 'Debug/.pch': No such file or directory错误处理

遇到这样的问题,百度找到“”,提到: 可以使用右键点击项目工程中的该cpp文件,选择setting,在c...
  • superdont
  • superdont
  • 2012年07月26日 21:18
  • 7850

zipimport.ZipImportError: bad local file header错误的解决办法

在debian/ubuntu系中比较常见。(更新不勤快的发行版不是好发行版) 这个是setuptools老版本(0.6)中已被查明的BUG,在新版本中已经得到解决,使用老版本的可以用以下命令升级se...
  • Scape1989
  • Scape1989
  • 2014年01月18日 14:21
  • 3694

破解IDEA Ultimate2017

IDEA到期了,随后简单破解之。图1 图2 (1)点击图1中的“Enter License” (2)选择License Server (3)输入
  • daihuimaozideren
  • daihuimaozideren
  • 2017年12月03日 09:20
  • 483

the file is possibly corrupt. the file header checksum does not match the computed checksum故障解决办法

the file is possibly corrupt. the file header checksum does not match the computed checksum故障解决办法 现象...
  • lhfeng
  • lhfeng
  • 2010年12月22日 11:09
  • 27404
您举报文章:The Ultimate (DLL) Header File