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

Статья
11/20/2024

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

Синтаксис

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

Параметры

[in] lpName

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

\\.\mailslot\[пути]имя

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

[in] nMaxMessageSize

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

[in] lReadTimeout

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

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

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

[in, optional] lpSecurityAttributes

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

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

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

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

Замечания

Mailslot существует до тех пор, пока не будет задано одно из следующих условий:

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

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

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

Формат	Употребление
\\.\mailslot\имя	Извлекает дескриптор клиента в локальный почтовый объект.
\\имя компьютера\mailslot\имя	Извлекает дескриптор клиента в удаленный почтовый объект.
\\имя домена\mailslot\имя	Извлекает дескриптор клиента ко всем почтовым с указанным именем в указанном домене.
\\\mailslot\имя*	Извлекает дескриптор клиента ко всем почтовым с указанным именем в основном домене системы.

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

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

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

Примеры

Пример см. в статье СозданиеMailslot.

Заметка

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 2000 Профессиональный [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
целевая платформа	Виндоус
заголовка	winbase.h (включая Windows.h)
библиотеки	Kernel32.lib
DLL	Kernel32.dll