Основные функции реализации почтового ящика

Функция Сгеа t е Mailslot

HANDLE СгеаtеMailslot(

LPCTSTR lpName,                  // Адрес имени канала Mailslot

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

DWORD  IReadTimeout,    // Время ожидания для чтения

LPSECURITY_ATTRIBUTES lpSecurityAttributes); // Адрес структуры защиты

    Через параметр lpName  необходимо передать функции СгеаtеMailslot адрес строки символов с именем канала MailSlot. Имя почтового ящика имеет следующий вид:

\\сервер\ MailSlot\[Путь]ИмяКанала

В этом имени путь является необязательной компонентой. Тем не менее, можно указать его аналогично тому, как это делается для файлов.

Имя - сервер\- должно быть представлено точкой, так как сервер можно создать только на локальном компьютере.

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

С помощью параметра IReadTimeout серверное приложение может задать время ожидания для операции чтения в миллисекундах, по истечении которого функция чтения вернет код ошибки. При указании в этом параметре значение MAILSLOT_WAIT_FOREVER., ожидание будет бесконечным.

Параметр lpSecurityAttributes задает адрес структуры защиты, который обычно в приложениях указывается как NULL для совместимости с потребительскими версиями ОС Windows, которые не поддерживают систему безопасности.

При ошибке функция Сгеаte MailSlot возвращается значение INVALID_HANDLE_VALUE. Код ошибки можно определить при помощи функции GetLastError.

 

Функция CreateFile

Прежде чем приступить к работе с каналом Mailslot, клиентский процесс должен его открыть. Использование функции CreateFile для открытия канала в клиентском процессе осуществляется следующим способом.

CreateFile(

lpszMailslotName, GENERIC_WRITE,

FILE_SHARE_READ, NULL, OPEN_EXISTING, 0, NULL).

Здесь в качестве первого параметра функции CreateFile передается имя канала Mailslot. Заметим, что можно открыть канал Mailslot, созданный на другой рабочей станции в сети. Для этого строка имени канала, передаваемая функции CreateFile, должна иметь следующий вид:

\\ИмяРабочейСтанции\ mailslоt \[Путь]ИмяКанала

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

\\ИмяДомена\mailslоt\[Путь]ИмяКанала

Для передачи сообщений одновременно всем рабочим станциям сети первичного домена имя задается следующим образом:

\\*\mailslot\[Путь]ИмяКанала

В качестве второго параметра функции CreateFile передается константа GENERIC_WRITE. Эта константа определяет, что над открываемым каналом будет выполняться операция записи. Напомним, что клиентский процесс может только посылать сообщения в канал Mailslot, но не читать их оттуда. Чтение сообщений из канала Mailslot осуществляет серверный процесс.

Третий параметр указан как FILESHAREREAD, и это тоже необходимо, так как сервер может читать сообщения, посылаемые одновременно несколькими клиентскими процессами.

Обратим также внимание на константу OPENEX1ST1NG. Она используется потому, что функция CreateFile открывает существующий канал, а не создает новый.

Функция WriteFile

Запись сообщений в канал Mailslot выполняет клиентский процесс, вызывая для этого функцию WriteFile стандартную API-функцию.

WriteFile(

HANDLE hMaiislot; char szBuf[512]; DWORD cbWritten;

WriteFile(hMailslot, szBuf, strlen(szBuf) + 1, ScbWritten, NULL);

В качестве первого параметра этой функции необходимо передать идентификатор канала Mailslot, полученный от функции CreateFile.

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

Функция ReadFile

Серверный процесс может читать сообщения из созданного им канала Mailslot при помощи API-функции

ReadFile(

HANDLE hMailslot;

char szBuf[512j;

DWORD cbRead;

ReadFile(hMailslot, szBuf, 512, ScbRead, NULL);

Через первый параметр функции ReadFile передается идентификатор созданного ранее канала Mailslot, полученный от функции CreateMailslot. Второй и третий параметры задают соответственно адрес буфера для сообщения и его размер.

Заметим, что перед выполнением операции чтения следует проверить состояние канала Mailslot. Если в нем нет сообщений, то функцию ReadFile вызывать не следует. Для проверки состояния канала можно воспользоваться функцией GetMailslotlnfo.

Функция GetMailslotlnfo

Серверный процесс может определить текущее состояние канала Mailslot по его идентификатору с помощью функции GetMailslotlnfo.

BOOL GetMailslotlnfo(

HANDLE hMailslot,  // идентификатор канала Mailslot

LPDWORD lpMaxMessageSize, // адрес максимального размера

// сообщения

LPDWORD lpNextSize, // адрес размера следующего сообщения

LPDWORD lpMessageCount, // адрес количества сообщений

LPDWORD lpReadTimeout); // адрес времени ожидания

Через параметр hMailslot функции передается идентификатор канала Mailslot, состояние которого необходимо определить.

Остальные параметры задаются как указатели на переменные типа DWORD, в которые будут записаны параметры состояния канала Mailslot.

В переменную, адрес которой передается через параметр lpMaxMessageSize, после возвращения из функции GetMailslotlnfo будет записан максимальный размер сообщения. Можно использовать это значение для динамического получения буфера памяти, в который это сообщение будет прочитано функцией ReadFile. В переменную, адрес которой указан через параметр lpNextSize, записывается размер следующего сообщения, если оно есть в канале. Если же в канале больше нет сообщений, в эту переменную будет записана константа MAILSLOTNOMESSAGE. С помощью параметра lpMessageCount можно определить количество сообщений, записанных в канал клиентскими процессами. Если это количество равно нулю, не следует вызывать функцию ReadFile для чтения несуществующего сообщения. И, наконец, в переменную, адрес которой задается в параметре lpReadTimeout, записывается текущее время ожидания, установленное для канала (в миллисекундах). Если не нужна вся информация, которую можно получить с помощью функции GetMailslotlnfo, некоторые из ее параметров (кроме, разумеется, первого) можно указать как NULL.

В случае успешного завершения функция GetMailslotlnfo возвращает значение TRUE, a при ошибке - FALSE. Код ошибки можно получить, вызвав функцию GetLastError.

Функция SetMailslotlnfo

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

BOOL SetMailslotlnfo(

HANDLE hMailslot, // идентификатор канала Mailslot

DWORD dwReadTimeout); // время ожидания

Через параметр hMailslot функции SetMailslotlnfo передается идентификатор каналаMailslot, для которого нужно изменить время ожидания.

Новое значение времени ожидания в миллисекундах задается через параметр dwReadTimeout. Можно указать здесь константы 0 или MAIL_SLOT_WAITFOREVER. В первом случае функции, работающие с каналом, вернут управление немедленно, во втором - будут находиться в состоянии ожидания до тех пор, пока не завершится выполняемая операция.

Примеры консольных приложений простого сервера и клиента почтового ящика представлены в приложении.