Тарас Сорока - Русский справочник по Win32 API Страница 22

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

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

В случае неудачи возвращается NULL . Вызов функции также закончится неудачей при неверном значении параметра hwndCtl .

Комментарии

GetDlgCtrlID также принимает в качестве параметров и дескрипторы дочерних окон, наравне с дескрипторами элементов управления в диалоговых окнах. Приложение устанавливает идентификатор для дочернего окна, присваивая значение идентификатора параметру hMenu при вызове функций CreateWindow или CreateWindowEx .

Хотя функция GetDlgCtrlID может вернуть значение в случае, если параметр hwndCtl идентифицирует окно верхнего уровня, такие окна не могут иметь идентификаторов и, соответственно, не будет возвращено правильного значения.

См . также

CreateWindow, CreateWindowEx, GetDlgItem .

Мэйлслоты

CreateMailslot

Функция 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 // тайм - аут чтения

);

Параметры

hMailslot - идентифицирует мэйлслот. Этот дескриптор должна создать функция CreateMailslot .

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

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

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

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

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

В случае успеха возвращается ненулевое значение.

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

Комментарии

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