Which rules to observe when projecting an API?
Follow this rules when creating a library.
| В первом приближении
|
- Функции должны экспортироваться по ординалам.
- К dll должен прилагаться .h-файл с описанием функций
- Если интерфейс опубликован, то менять его нельзя.
Если нужны новые функции, исправленные, то добавляй их как новые.
|
| Don't return pointers |
Functions, messages, methods and other structures of API
shouldn't return pointers. Better use handles.
Functions shouldn't allocate the memory by themselves and pass
it to calling process. The calling process must allocate memory
and free it. Study the examples in OS/2 Toolkit.
|
|
Возможность расширять структуры в будущем
|
Структуры данных должны позволять в дальнейшем вводить новые поля.
Т.е. каждый составной тип первым полем должен иметь переменную с
информацией о размере структуры. Примеры см. в OS/2 Toolkit. При
передаче клиентом в функцию структуры (буфера) меньшей длины,
структура должна заполняться частично. Т.е. если API использовал
ранее структуру типа:
struct DemoType1 {
USHORT size;
LONG item1;
};
А потом стал использовать
struct DemoType2 {
USHORT size;
LONG item1;
PSZ item2;
};
То при передаче клиентом буфера размером sizeof(DemoType1)
должны быть заполнены поля по Item1 (включительно), несмотря
на то, что функция API может заполнить и более полную структуру.
|
| Fix the alignment |
The structures used between the library and program
should keep the size of the structure
USHORT size;
Fix the alignment of the structures, the .h file should contain:
#pragma pack(1)
|
| Export by ordinals, not names |
Экспортировать надо всегда по ординалам
(чтобы старые программы работали с новыми версиями .dll).
Импортировать надо всегда по имени, а не по ординалам.
OpenWatcom, wlink.exe
Добавьте в .def на линковку dll:
EXPORTS
RegisterPluginProc @501 NONAME
если в makefile, то
export VfmParserVersion.1
Visual Age for C, v.4
option link(export, "PLINIT",,1,NONAME)
|
| Simple C |
Don't use C++ inside dll library
|
| Other mistakes |
Don't use functions abort() and exit() inside the libraries
|
|
Parameters: char * or const char*
|
Declare parameters as const char*
Char* parameters can be changed (by mistake) inside the function.
|
| |
