CreateFile - функция Win 32 API

Все примеры приведены для среды разработки Embarcadero RAD Studio 11 (C++ Builder)

В ОС Windows работа с последовательными и параллельными портами ввода-вывода производится как с объектами файловой системы. Для этого используются стандартные функции Win32 API:

 -  CreateFile - открывает порт и получает его дескриптор (HANDLE).

 -  CloseHandle - закрывает ранее открытый порт по его дескриптору.

 -  ReadFile - читает данные из порта.

 -  WriteFile - отправляет данные в порт.

Описание функции CreateFile

Открыть порт и получить его дескриптор для дальнейшей работы позволяет функция CreateFile. Прототип функции находится в файле fileapi.h.

WINBASEAPI  HANDLE  WINAPI  CreateFileW(
    _In_     LPCWSTR lpFileName,
    _In_     DWORD dwDesiredAccess,
    _In_     DWORD dwShareMode,
    _In_opt_ LPSECURITY_ATTRIBUTES lpSecurityAttributes,
    _In_     DWORD dwCreationDisposition,
    _In_     DWORD dwFlagsAndAttributes,
    _In_opt_ HANDLE hTemplateFile
);

#ifdef UNICODE
#define CreateFile  CreateFileW
#else
#define CreateFile  CreateFileA
#endif // !UNICODE

Если строки кодируются юникодом, вызывается функция CreateFileW, использующая "широкий" тип сторки: wstr - wide string, использующая не менее двух байт на символ. Иначе вызывается функция CreateFileA, использующая обычную однобайтную кодировку ASCII с типом строки; cstr - c string. Для примера используем функцию с "широкой строкой".

Возвращаемое значение:

 -  HANDLE hFile - указатель типа void на дескриптор открываемого порта. При ошибке функция возвращает нулевой указатель (NULL или nullptr).

Параметры функции:

 -  LPCWSTR lpFileName - указатель на "широкую" строку: имя коммуникационного порта. Последовательные порты имеют простые имена "COM1", "COM2", "COM3"...

 -  DWORD dwDesiredAccess - тип доступа к файлу или порту. Для портов с обменом в обе стороны: GENERIC_READ | GENERIC_WRITE

//  These are the generic rights.
                          //- winnt.h
#define GENERIC_READ      (0x80000000L)  //- операции чтения
#define GENERIC_WRITE     (0x40000000L)  //- операции записи
#define GENERIC_EXECUTE   (0x20000000L)  //- операции выполнения (не работает с портами)
#define GENERIC_ALL       (0x10000000L)  //- все операции  (не работает с портами)

 -  DWORD dwShareMode - параметры совместного доступа к файлу. Неприменимо для коммуникационных портов и устанавливается в 0.

 -  LPSECURITY_ATTRIBUTES lpSecurityAttributes - атрибуты защиты файла. Неприменимо для коммуникационных портов и устанавливается в NULL.

 -  DWORD dwCreationDisposition - файловые авторежимы. Для коммуникационных портов всегда OPEN_EXISTING.

//- fileapi.h
#define CREATE_NEW          1
#define CREATE_ALWAYS       2
#define OPEN_EXISTING       3
#define OPEN_ALWAYS         4
#define TRUNCATE_EXISTING   5

 -  DWORD dwFlagsAndAttributes - флаги и атрибуты создаваемого файла. Для коммуникационных портов используются только: 0 - для синхронного режима обмена, FILE_FLAG_OVERLAPPED - для асинхронного режима обмена.

//  These are flags supported through CreateFile (W7) and CreateFile2 (W8 and beyond)
                               //- winbase.h
#define FILE_FLAG_WRITE_THROUGH         0x80000000
#define FILE_FLAG_OVERLAPPED            0x40000000
#define FILE_FLAG_NO_BUFFERING          0x20000000
#define FILE_FLAG_RANDOM_ACCESS         0x10000000
#define FILE_FLAG_SEQUENTIAL_SCAN       0x08000000
#define FILE_FLAG_DELETE_ON_CLOSE       0x04000000
#define FILE_FLAG_BACKUP_SEMANTICS      0x02000000
#define FILE_FLAG_POSIX_SEMANTICS       0x01000000
#define FILE_FLAG_SESSION_AWARE         0x00800000
#define FILE_FLAG_OPEN_REPARSE_POINT    0x00200000
#define FILE_FLAG_OPEN_NO_RECALL        0x00100000
#define FILE_FLAG_FIRST_PIPE_INSTANCE   0x00080000

 -  HANDLE hTemplateFile - дескриптор файла-шаблона. При работе с коммуникационными портами всегда NULL.

Модификаторы вызова функции и аргументов:

-  WINBASEAPI (он же DECLSPEC_IMPORT, или __declspec(dllimport)) - указывает на класс хранилища функции. Позволяет получить доступ к объектам библиотеки DLL.

-  WINAPI (он же __stdcall) - соглашение о вызове функций Win32 API: аргументы передаются справа налево через стек; очистка стека ложится на вызываемую функцию; возвращаемое значение в регистре eax.

-  _In_ и _In_opt_ - макросы, которые вызываются только при использовании SAL2.0 — языка заметок для драйверов Windows (способ описания свойств функций, параметров, возвращаемых значений, структур и полей структуры). В данном случае не используются.

Описание функции CloseHandle

Функция CloseHandle закрывает ранее открытый порт. Прототип функции находится в файле handleapi.h.

WINBASEAPI  BOOL  WINAPI  CloseHandle(
    _In_ _Post_ptr_invalid_ HANDLE hObject
);

При успешном вызове функции возвращаемое значение будет ненулевым (true), при ошибке функция возвращает 0 (false). Информацию о ошибке можно получить, вызвав функцию GetLastError.

Параметр функции:

-  HANDLE hObject - дескриптор закрываемого объекта. В нашем случае дескриптор порта, открытый функцией CreateFile