Функция CreateMailslot создает мэйлслот с указанным именем и возвращает дескриптор, который мэйлслотовый сервер может использовать для выполнения операций над мэйлслотом. Мэйлслот локален относительно компьютера, который его создал. Если мэйлслот с указанным именем существует, то происходит ошибка.
HANDLE CreateMailslot (
LPCTSTR lpName , // указатель на строку с именем мэйлслота
DWORD nMaxMessageSize , // максимальный размер сообщения
DWORD lReadTimeout , // миллисекунды до тайм - аута чтения
LPSECURITY_ATTRIBUTES lpSecurityAttributes // указатель
// на структуру безопасности
);
Параметры
lpName - указывает на завершающуюся нулем строку, определяющую имя мэйлслота. Строка должна иметь следующий вид:
\\.\mailslot\[path]name
Поле name должно быть уникальным. Имя может включать множественные уровни псевдодиректорий, разделенных символами обратного слэша. Например, правильными именами являются \\.\ mailslot \ example_mailslot_name и \\.\mailslot\abc\def\ghi .
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\name |
Получает клиентский дескриптор локального мэйлслота. |
|
\\computername\mailslot\name |
Получает клиентский дескриптор удаленного мэйлслота. |
|
\\domainname\mailslot\name |
Получает клиентский дескриптор всех мэйлслотов с указанным именем в указанном домене. |
|
\\*\mailslot\name |
Получает клиентский дескриптор всех мэйлслотов с указанным именем в первичном домене системы. |
Если CreateFile определяет домен или использует звездочку для указания первичного домена системы, приложение не может записать в мэйлслот более 400 символов за раз. Если приложение попытается сделать это, вызов WriteFile завершится неудачей и GetLastError вернет ERROR_BAD_NETPATH .
Приложение должно указать флаг FILE_SHARE_READ при использовании CreateFile для получения клиентского дескриптора мэйлслота.
См. также
CloseHandle, CreateFile, GetMailslotInfo, SECURITY_ATTRIBUTES, SetMailslotInfo, WriteFile .
GetMailslotInfo
Функция GetMailslotInfo извлекает информацию об указанном мэйлслоте.
BOOL GetMailslotInfo (
HANDLE hMailslot , // дескриптор мэйлслота
LPDWORD lpMaxMessageSize , // адрес максимального размера сообщения
LPDWORD lpNextSize , // адрес размера следующего сообщения
LPDWORD lpMessageCount , // адрес количества сообщений
LPDWORD lpReadTimeout // адрес тайм - аута чтения
);
Параметры
hMailslot - идентифицирует мэйлслот. Этот дескриптор должна создать функция CreateMailslot .
lpMaxMessageSize - когда функция возвращает управление, указывает на буфер, определяющий максимальный размер письма в байтах, допустимый для этого мэйлслота. Эта величина должна быть больше или равна значению параметра cbMaxMsg функции CreateMailslot , создавшей мэйлслот. Значение параметра может быть равно нулю.
lpNextSize - когда функция возвращает управление, указывает на буфер, определяющий размер следующего письма в байтах. Следующая величина имеет специальное значение:
MAILSLOT_NO_MESSAGE - следующее сообщение отсутствует.
Значение параметра может быть равно нулю.
lpMessageCount - когда функция возвращает управление, указывает на буфер, определяющий количество сообщений, ждущих прочтения. Значение параметра может быть равно нулю.
lReadTimeout - указывает на буфер, определяющий количество времени, в миллисекундах, которое операция чтения может ждать сообщения, записанного в мэйлслот, до наступления тайм-аута. Параметр заполняется, когда функция возвращает управление. Значение параметра может быть равно нулю.
Возвращаемые значения
В случае успеха возвращается ненулевое значение.
В случае неудачи возвращается нуль. Для получения дополнительной информации об ошибке вызовите функцию GetLastError .
См. также
CreateMailslot, SetMailslotInfo .
SetMailslotInfo
Функция SetMailslotInfo устанавливает величину тайм-аута, используемую указанным мэйлслотом для операции чтения.
BOOL SetMailslotInfo (
HANDLE hMailslot , // дескриптор мэйлслота
DWORD lReadTimeout // тайм - аут чтения