Функция WSAQuerySocketSecurity (ws2tcpip.h)

Статья
08/28/2023

Функция WSAQuerySocketSecurity запрашивает сведения о безопасности, применяемой к подключению в сокете.

Синтаксис

INT WSAAPI WSAQuerySocketSecurity(
  [in]            SOCKET                               Socket,
  [in, optional]  const SOCKET_SECURITY_QUERY_TEMPLATE *SecurityQueryTemplate,
  [in]            ULONG                                SecurityQueryTemplateLen,
  [out, optional] SOCKET_SECURITY_QUERY_INFO           *SecurityQueryInfo,
  [in, out]       ULONG                                *SecurityQueryInfoLen,
  [in, optional]  LPWSAOVERLAPPED                      Overlapped,
  [in, optional]  LPWSAOVERLAPPED_COMPLETION_ROUTINE   CompletionRoutine
);

Параметры

[in] Socket

Дескриптор, определяющий сокет, для которого запрашиваются сведения о безопасности.

[in, optional] SecurityQueryTemplate

Указатель на структуру SOCKET_SECURITY_QUERY_TEMPLATE , задающую тип возвращаемых сведений запроса.

Структура SOCKET_SECURITY_QUERY_TEMPLATE , на которую указывает этот параметр, может содержать нули для всех участников запроса сведений о безопасности по умолчанию. При успешном возвращении в возвращенном параметре SecurityQueryInfo будет задан только элемент Flags в SOCKET_SECURITY_QUERY_INFO.

Этот параметр может быть указателем NULL , если параметр Socket был создан с помощью протокола IPPROTO_TCP. В этом случае возвращаемые сведения совпадают с тем, как если бы была передана структура SOCKET_SECURITY_QUERY_TEMPLATE со всеми значениями, равными нулю. Этот параметр следует указывать для сокета с протоколом IPPROTO_TCP , если требуется больше сведений о безопасности по умолчанию.

Если структура SOCKET_SECURITY_QUERY_TEMPLATE указана с не указанным элементом PeerTokenAccessMask (значение равно нулю), то функция WSAQuerySocketSecurity не вернет элементы PeerApplicationAccessTokenHandle и PeerMachineAccessTokenHandle в структуре SOCKET_SECURITY_QUERY_INFO .

Если параметр Socket был создан с протоколом, не равным IPPROTO_TCP, необходимо указать параметр SecurityQueryTemplate . В таких случаях член PeerAddress структуры SOCKET_SECURITY_QUERY_TEMPLATE должен указать семейство адресов AF_INET или AF_INET6, а также IP-адрес и номер порта однорангового узла.

[in] SecurityQueryTemplateLen

Размер параметра SecurityQueryTemplate в байтах.

Этот параметр может иметь нулевое значение, если параметр Socket был создан с помощью протокола IPPROTO_TCP. В противном случае этот параметр должен иметь размер структуры SOCKET_SECURITY_QUERY_TEMPLATE .

[out, optional] SecurityQueryInfo

Указатель на буфер, который получит структуру SOCKET_SECURITY_QUERY_INFO , содержащую запрашиваемую информацию. Это значение может быть равно NULL для запроса размера выходного буфера.

[in, out] SecurityQueryInfoLen

На входных данных — указатель на размер параметра SecurityQueryInfo в байтах. Если буфер слишком мал для получения запрашиваемой информации, вызов вернет SOCKET_ERROR, а количество байтов, необходимых для возврата запрашиваемой информации, будет задано в значении, на которое указывает этот параметр. При успешном вызове возвращается количество скопированных байтов.

[in, optional] Overlapped

Указатель на структуру WSAOVERLAPPED . Этот параметр игнорируется для неперекрывающихся сокетов.

[in, optional] CompletionRoutine

Указатель на подпрограмму завершения, вызываемую при завершении операции. Этот параметр игнорируется для неперекрывающихся сокетов.

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

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

Ниже перечислены некоторые возможные коды ошибок.

Код ошибки	Значение
WSAEAFNOSUPPORT	Указанное семейство адресов не поддерживается.
WSAECONNRESET	Для сокета потока виртуальная цепь была сброшена удаленной стороной. Приложение должно закрыть сокет, поскольку он больше не может использоваться. Для сокета датаграммы UDP эта ошибка указывает на то, что предыдущая операция отправки привела к сообщению ICMP "Порт недоступен".
WSAEFAULT	Система обнаружила недопустимый адрес указателя при попытке использовать параметр . Эта ошибка возвращается, если параметр SecurityQueryInfoLen был указателем NULL .
WSAEINVAL	Передан недопустимый параметр. Эта ошибка возвращается, если сокет, переданный в параметре Socket , не был создан с семейством адресов AF_INET или AF_INET6 и типом сокета SOCK_DGRAM или SOCK_STREAM.
WSAEMSGSIZE	Переданный буфер был слишком мал. Эта ошибка возвращается для параметра Socket , если протокол не был IPPROTO_TCP , если параметр SecurityQueryInfo является указателем NULL или параметр SecurityQueryTemplateLen меньше размера структуры SOCKET_SECURITY_QUERY_TEMPLATE .
WSAENOTSOCK	Дескриптор, переданный в параметре Socket , не является допустимым сокетом.

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

Для сокетов, ориентированных на подключение, предпочтительно вызывать функцию WSAQuerySocketSecurity сразу после установки соединения. Для сокетов без подключения предпочтительно вызывать функцию WSAQuerySocketSecurity сразу после отправки данных на новый адрес однорангового узла или получения с нового однорангового адреса. Функцию WSAQuerySocketSecurity можно вызывать несколько раз в одном сокете.

Эта функция упрощает вызов функции WSAIoctl с параметром dwIoControlCode, для SIO_QUERY_SECURITY.

Функция WSAQuerySocketSecurity может вызываться в параметре Socket , созданном с семейством адресов AF_INET или AF_INET6.

Если параметр Socket был создан с протоколом IPPROTO_TCP, параметр SecurityQueryTemplate может иметь значение NULL , а параметр SecurityQueryTemplateLen — ноль. В противном случае параметр SecurityQueryTemplate должен указывать на структуру SOCKET_SECURITY_QUERY_TEMPLATE .

Для клиентского приложения, использующее сокеты, ориентированные на подключение (сокет, созданный с помощью протокола IPPROTO_TCP), функция WSAQuerySocketSecurity должна вызываться после возврата функции connect, ConnectEx или WSAConnect . Для серверного приложения, использующее сокеты, ориентированные на подключение (протокол IPPROTO_TCP), функция WSAQuerySocketSecurity должна вызываться после возврата функции accept, AcceptEx или WSAAccept .

Для сокетов без подключения (сокетов, созданных с помощью протокола IPPROTO_UDP), приложение должно вызывать функцию WSAQuerySocketSecurity сразу после возврата вызова WSASendTo или WSARecvFrom для нового однорангового адреса.

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

Семейство адресов параметра Socket должно быть AF_INET или AF_INET6.
Тип сокета должен быть SOCK_STREAM или SOCK_DGRAM.

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista [только классические приложения]
Минимальная версия сервера	Windows Server 2008 [только классические приложения]
Целевая платформа	Windows
Header	ws2tcpip.h
Библиотека	Fwpuclnt.lib
DLL	Fwpuclnt.dll