Функция CreateMailslotA (winbase.h)

Статья
08/27/2023

Создает mailslot с указанным именем и возвращает дескриптор, который сервер mailslot может использовать для выполнения операций с ним. Mailslot является локальным для компьютера, который его создает. Если почтовый слоот с указанным именем уже существует, возникает ошибка.

Синтаксис

HANDLE CreateMailslotA(
  [in]           LPCSTR                lpName,
  [in]           DWORD                 nMaxMessageSize,
  [in]           DWORD                 lReadTimeout,
  [in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes
);

Параметры

[in] lpName

Имя почтового объекта. Это имя должно иметь следующую форму:

\\.\mailslot\[path]name

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

[in] nMaxMessageSize

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

[in] lReadTimeout

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

Значение	Значение
0	Возвращает немедленно, если сообщение отсутствует. (Система не рассматривает немедленное возвращение как ошибку.)
MAILSLOT_WAIT_FOREVER ((DWORD)-1)	Вечное ожидание сообщения.

Это значение времени ожидания применяется ко всем последующим операциям чтения и ко всем унаследованным дескрипторам почтового объекта.

[in, optional] lpSecurityAttributes

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

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

Если функция выполняется успешно, возвращаемое значение является дескриптором для почтового слоя для использования в операциях с почтовым слоем сервера. Дескриптор, возвращаемый этой функцией, является асинхронным или перекрывающимся.

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

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

Система использует второй метод для уничтожения почтовых слоотов.

Чтобы записать сообщение в mailslot, процесс использует функцию CreateFile , указывая имя почтового слоя в одном из следующих форматов.

Формат	Использование
\\.\mailslot\name	Извлекает дескриптор клиента в локальный почтовый слоот.
\\computername\mailslot\name	Извлекает дескриптор клиента в удаленный почтовый слоот.
\\domainname\mailslot\name	Извлекает дескриптор клиента для всех почтовых слоотов с указанным именем в указанном домене.
\\\mailslot\name*	Извлекает дескриптор клиента ко всем почтовым слокам с указанным именем в основном домене системы.

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

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

Если для доступа к несуществующему почтовому слою вызывается CreateFile , будет задан код ошибки ERROR_FILE_NOT_FOUND .

Примеры

Пример см. в разделе Создание mailslot.

Примечание

Заголовок winbase.h определяет CreateMailslot как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	winbase.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll