CreateMailslot

CreateMailslot

Функция CreateMailslot создает мэйлслот с указанным именем и возвращает дескриптор, который мэйлслотовый сервер может использовать для выполнения операций над мэйлслотом. Мэйлслот локален относительно компьютера, который его создал. Если мэйлслот с указанным именем существует, то происходит ошибка.

HANDLE CreateMailslot (

LPCTSTR lpName , // указатель на строку с именем мэйлслота

DWORD nMaxMessageSize , // максимальный размер сообщения

DWORD lReadTimeout , // миллисекунды до тайм - аута чтения

LPSECURITY_ATTRIBUTES lpSecurityAttributes // указатель

// на структуру безопасности

);

Параметры

lpName - указывает на завершающуюся нулем строку, определяющую имя мэйлслота. Строка должна иметь следующий вид:

\.mailslot[path]name

Поле name должно быть уникальным. Имя может включать множественные уровни псевдодиректорий, разделенных символами обратного слэша. Например, правильными именами являются \. mailslot example_mailslot_name и \.mailslotabcdefghi .

nMaxMessageSize - определяет максимальный размер сообщения в байтах, которое может быть записано в мэйлслот. Для указания того, что сообщение может быть любого размера, установите значение этого параметра в нуль.

lReadTimeout - определяет количество времени, в миллисекундах, которое операция чтения может ждать сообщения, записанного в мэйлслот, до наступления тайм-аута. Следующие величины имеют специальные значения:

0 - функция возвращает управление немедленно, если в мэйлслоте отсутствует сообщение. (Система не трактует немедленное возвращение как ошибку.)

MAILSLOT_WAIT_FOREVER - ждет до тех пор, пока не придет сообщение.

Величина тайм-аута применяется ко всем последующим операциям чтения и всем унаследованным дескрипторам мэйлслота.

lpSecurityAttributes - указывает на структуру типа SECURITY_ATTRIBUTES , которая определяет, может ли возвращаемый дескриптор мэйлслота наследоваться дочерними процессами. Если значение lpSecurityAttributes равно NULL, дескриптор не может быть унаследован.

Windows NT : Член lpSecurityDescriptor структуры определяет дескриптор безопасности для нового мэйлслота. Если значение lpSecurityDescriptor равно NULL, мэйлслот получает дескриптор безопасности по умолчанию.

Windows 95: Член lpSecurityDescriptor структуры игнорируется.

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

В случае успеха возвращается дескриптор мэйлслота.

В случае неудачи возвращается INVALID_HANDLE_VALUE. Для получения дополнительной информации об ошибке вызовите функцию GetLastError .

Комментарии

Мэйлслот существует до тех пор, пока:

Последний (возможно, унаследованный или дублированный) дескриптор не закрыт функцией CloseHandle .

Процесс, владеющий последним (возможно, унаследованным или дублированным) дескриптором, существует.

И Windows NT, и Windows 95 используют второй метод для разрушения мэйлслотов.

Для записи сообщения в мэйлслот процесс использует функцию CreateFile , указав имя мэйлслота в одном из следующих форматов:

Формат

Использование

\.mailslot ame

Получает клиентский дескриптор локального мэйлслота.

\computernamemailslot ame

Получает клиентский дескриптор удаленного мэйлслота.

\domainnamemailslot ame

Получает клиентский дескриптор всех мэйлслотов с указанным именем в указанном домене.

\*mailslot ame

Получает клиентский дескриптор всех мэйлслотов с указанным именем в первичном домене системы.

Если CreateFile определяет домен или использует звездочку для указания первичного домена системы, приложение не может записать в мэйлслот более 400 символов за раз. Если приложение попытается сделать это, вызов WriteFile завершится неудачей и GetLastError вернет ERROR_BAD_NETPATH .

Приложение должно указать флаг FILE_SHARE_READ при использовании CreateFile для получения клиентского дескриптора мэйлслота.

См. также

CloseHandle, CreateFile, GetMailslotInfo, SECURITY_ATTRIBUTES, SetMailslotInfo, WriteFile .