Функция WSAsyncGetServByPort (winsock.h)
Функция WSAsyncGetServByPort асинхронно извлекает сведения о службе, соответствующие порту и протоколу.
Синтаксис
HANDLE WSAAsyncGetServByPort(
[in] HWND hWnd,
[in] u_int wMsg,
[in] int port,
[in] const char *proto,
[out] char *buf,
[in] int buflen
);
Параметры
[in] hWnd
Дескриптор окна, которое должно получать сообщение после завершения асинхронного запроса.
[in] wMsg
Сообщение, которое будет получено по завершении асинхронного запроса.
[in] port
Порт для службы в порядке сетевых байтов.
[in] proto
Указатель на имя протокола. Это значение может иметь значение NULL. В этом случае WSAsyncGetServByPort будет искать первую запись службы, для которой s_port совпадать с заданным портом. В противном случае WSAsyncGetServByPort соответствует порту и proto.
[out] buf
Указатель на область данных для получения данных. Область данных должна быть больше, чем размер обслуживающей структуры, так как область данных используется сокетами Windows для размещения обслуживающей структуры и всех данных, на которые ссылаются члены структуры обслуживания . Рекомендуется использовать буфер в байтах MAXGETHOSTSTRUCT.
[in] buflen
Размер области данных для параметра buf в байтах.
Возвращаемое значение
Возвращаемое значение указывает, была ли успешно инициирована асинхронная операция. Это не означает успех или неудачу самой операции.
Если ошибка не возникает, WSAsyncGetServByPort возвращает ненулевое значение типа HANDLE , которое является асинхронным дескриптором задачи для запроса (не следует путать с windows HTASK). Это значение можно использовать двумя способами. Его можно использовать для отмены операции с помощью WSACancelAsyncRequest или для сопоставления асинхронных операций и сообщений завершения путем проверки параметра сообщения wParam .
Если не удалось инициировать асинхронную операцию, WSAsyncGetServByPort возвращает нулевое значение, и конкретный номер ошибки можно получить, вызвав WSAGetLastError.
При получении сообщения в окне приложения можно задать следующие коды ошибок. Как описано выше, их можно извлечь из lParam в ответном сообщении с помощью макроса WSAGETASYNCERROR .
| Код ошибки | Значение |
|---|---|
| Произошел сбой сетевой подсистемы. | |
| Недостаточно места в буфере. | |
| Параметр proto или buf не входит в допустимую часть адресного пространства процесса. | |
| Достоверный порт ответа не найден. | |
| Неавторизированный порт не найден или сбой сервера. | |
| Неустранимые ошибки, база данных служб недоступна. | |
| Допустимое имя, без записи данных запрошенного типа. |
Во время вызова функции могут возникнуть следующие ошибки, указывающие на то, что не удалось инициировать асинхронную операцию.
| Код ошибки | Значение |
|---|---|
| WSANOTINITIALISED | Перед использованием этой функции должен произойти успешный вызов WSAStartup . |
| WSAENETDOWN | Произошел сбой сетевой подсистемы. |
| WSAEINPROGRESS | Выполняется блокирующий вызов Windows Sockets 1.1 или поставщик услуг по-прежнему обрабатывает функцию обратного вызова. |
| WSAEWOULDBLOCK | В настоящее время асинхронную операцию невозможно запланировать из-за ограничений ресурсов или других ограничений в реализации сокетов Windows. |
Комментарии
Функция WSAsyncGetServByPort является асинхронной версией getservbyport и используется для получения сведений о службе, соответствующих номеру порта. Сокеты Windows инициируют операцию и немедленно возвращаются вызывающей стороне, передавая непрозрачный асинхронный дескриптор задачи, который приложение может использовать для идентификации операции. После завершения операции результаты (если таковые имеются) копируются в буфер, предоставленный вызывающим объектом, и сообщение отправляется в окно приложения.
После завершения асинхронной операции окно приложения, указанное параметром hWnd , получает сообщение в параметре wMsg . Параметр wParam содержит дескриптор асинхронной задачи, возвращенный исходным вызовом функции. Высокие 16 бит lParam содержат любой код ошибки. Код ошибки может быть любой ошибкой, как определено в Winsock2.h. Код ошибки, равный нулю, указывает на успешное завершение асинхронной операции.
При успешном завершении буфер, указанный в исходном вызове функции, содержит обслуживаемую структуру. Чтобы получить доступ к членам этой структуры, исходный адрес буфера должен быть приведен к указателю обслуживаемой структуры и обращаться к ней соответствующим образом.
Если код ошибки — WSAENOBUFS, размер буфера, указанного buflen в исходном вызове, был слишком мал, чтобы содержать все полученные сведения. В этом случае низкие 16 бит lParam содержат размер буфера, необходимый для предоставления всей необходимой информации. Если приложение решит, что частичные данные неадекватны, оно может повторно выполнить вызов функции WSAsyncGetServByPort с буфером, достаточно большим для получения всех нужных сведений (т. е. не меньше низких 16 бит lParam).
Буфер, указанный для этой функции, используется сокетами Windows для создания обслуживаемой структуры вместе с содержимым областей данных, на которые ссылаются члены одной и той же обслуживаемой структуры. Чтобы избежать ошибки WSAENOBUFS , приложение должно предоставить буфер не менее байтОВ MAXGETHOSTSTRUCT (как определено в Winsock2.h).
Код ошибки и длина буфера должны быть извлечены из lParam с помощью макросов WSAGETASYNCERROR и WSAGETASYNCBUFLEN, определенных в Winsock2.h как:
#include <windows.h>
#define WSAGETASYNCBUFLEN(lParam) LOWORD(lParam)
#define WSAGETASYNCERROR(lParam) HIWORD(lParam)
Использование этих макросов обеспечит максимальную переносимость исходного кода для приложения.
Требования
| Минимальная версия клиента | Windows 2000 Professional [только классические приложения] |
| Минимальная версия сервера | Windows 2000 Server [только классические приложения] |
| Целевая платформа | Windows |
| Header | winsock.h (включая Winsock2.h) |
| Библиотека | Ws2_32.lib |
| DLL | Ws2_32.dll |