Функция CallNamedPipe
Обычно сценарий взаимодействия клиентского процесса с серверным заключается в выполнении следующих операций:
- подключение к каналу с помощью функции CreateFile;
- выполнение операций чтения или записи такими функциями как ReadFile или WriteFile;
- отключение от канала функцией CloseHandle.
Функция CallNamedPipe позволяет выполнить эти операции за один прием, при условии что канал открыт в режиме передачи сообщений и что клиент посылает одно сообщение серверу и в ответ также получает от сервера одно сообщение.
Ниже мы привели прототип функции CallNamedPipe:
BOOL CallNamedPipe(
LPCTSTR lpNamedPipeName, // адрес имени канала
LPVOID lpOutBuffer, // адрес буфера для записи
DWORD nOutBufferSize, // размер буфера для записи
LPVOID lpInBuffer, // адрес буфера для чтения
DWORD nInBufferSize, // размер буфера для чтения
LPDWORD lpBytesRead, // адрес переменной для записи
// количества прочитанных байт данных
DWORD nTimeOut); // время ожидания в миллисекундах
Перед вызовом функции CallNamedPipe вы должны записать в параметр lpNamedPipeName указатель на текстовую строку, содержащую имя канала Pipe. При формировании этой строки вы должны руководствоваться теми же правилами, что и при использовании функции CreateFile.
Кроме имени канала, вы также должны подготовить буфер, содержащий передаваемые через канал данные. Адрес и размер этого буфера следует указать функции CallNamedPipe, соответственно, через параметры lpOutBuffer и nOutBufferSize.
Данные, полученные от сервера в ответ на посланное ему сообщение, будут записаны в буфер, который вы тоже должны подготовить заранее. Адрес этого буфера необходимо указать через параметр lpInBuffer, а размер буфера - через параметр nInBufferSize.
В переменную, адрес которой указан через параметр lpBytesRead, записывается количество байт, полученных через канал от сервера.
Параметр nTimeOut определяет, в течении какого времени функция CallNamedPipe будет ожидать доступности канала Pipe, прежде чем она вернет код ошибки. Помимо численного значения в миллисекундах, вы можете указать в этом параметре одну из следующих констант:
| Константа | Описание | ||
| NMPWAIT_NOWAIT | Ожидание канала Pipe не выполняется. Если канал не доступен, функция CallNamedPipe сразу возвращает код ошибки | ||
| NMPWAIT_WAIT_FOREVER | Ожидание выполняется бесконечно долго | ||
| NMPWAIT_USE_DEFAULT_WAIT | Ожидание выполняется в течении периода времени, указанного при вызове функции CreateNamedPipe |
В случае успешного завершения функция CallNamedPipe возвращает значение TRUE, а при ошибке - FALSE. Код ошибки можно получить, вызвав функцию GetLastError.
Заметим, что может возникнуть ситуация, при которой длина сообщения, полученного от сервера, превосходит размер буфера, предусмотренного процессом. В этом случае функция CallNamedPipe завершится с ошибкой, а функция GetLastError вернет значение ERROR_MORE_DATA. Не существует никакого способа получить через канал оставшуюся часть сообщения, так как перед возвращением управления функция CallNamedPipe закрывает канал с сервером.
