PFN_WSK_GET_LOCAL_ADDRESS fonction de rappel (wsk.h)

Article
03/05/2024

La fonction WskGetLocalAddress récupère l’adresse de transport locale d’un socket.

Syntaxe

PFN_WSK_GET_LOCAL_ADDRESS PfnWskGetLocalAddress;

NTSTATUS PfnWskGetLocalAddress(
  [in]      PWSK_SOCKET Socket,
  [out]     PSOCKADDR LocalAddress,
  [in, out] PIRP Irp
)
{...}

Paramètres

[in] Socket

Pointeur vers une structure WSK_SOCKET qui spécifie l’objet socket pour le socket interrogé.

[out] LocalAddress

Pointeur vers une mémoire tampon allouée à l’appelant qui reçoit l’adresse de transport locale du socket. La mémoire tampon doit se trouver dans la mémoire non paginée. La mémoire tampon doit également être suffisamment grande pour contenir le type de structure SOCKADDR spécifique qui correspond à la famille d’adresses spécifiée par l’application WSK lors de la création du socket.

Pour un socket orienté connexion accepté par l’application WSK sur un socket d’écoute, la famille d’adresses est identique à la famille d’adresses spécifiée par l’application WSK lors de la création du socket d’écoute.

[in, out] Irp

Pointeur vers un IRP alloué à l’appelant que le sous-système WSK utilise pour effectuer l’opération de récupération de manière asynchrone. Pour plus d’informations sur l’utilisation des runtimes d’intégration avec les fonctions WSK, consultez Utilisation des runtimes d’intégration avec les fonctions du noyau Winsock.

Valeur retournée

WskGetLocalAddress retourne l’un des codes NTSTATUS suivants :

Code de retour	Description
STATUS_SUCCESS	L’adresse de transport locale du socket a été récupérée avec succès. L’IRP sera complété avec succès status.
STATUS_PENDING	Le sous-système WSK n’a pas pu récupérer immédiatement l’adresse de transport locale du socket. Le sous-système WSK termine l’IRP une fois qu’il a récupéré l’adresse de transport locale pour le socket. La status de l’opération de récupération est retournée dans le champ IoStatus.Status de l’IRP.
STATUS_INVALID_DEVICE_STATE	Le socket n’est pas lié à une adresse de transport locale. L’IRP sera terminé avec l’échec status.
STATUS_FILE_FORCED_CLOSED	Le socket n’est plus fonctionnel. L’IRP sera terminé avec l’échec status. L’application WSK doit appeler la fonction WskCloseSocket pour fermer le socket dès que possible.
Autres codes status	Une erreur est survenue. L’IRP sera terminé avec l’échec status.

Remarques

Une application WSK peut appeler la fonction WskGetLocalAddress uniquement sur un socket qui a été lié à une adresse de transport locale.

Un socket d’écoute, de datagramme ou de flux est lié à une adresse de transport locale lorsque l’application WSK appelle la fonction WskBind .

Un socket orienté connexion est lié à une adresse de transport locale de l’une des manières suivantes :

L’application WSK appelle la fonction WskBind .
L’application WSK crée, lie et connecte le socket en appelant la fonction WskSocketConnect .
Le sous-système WSK lie le socket lorsque l’application WSK accepte une demande de connexion entrante sur un socket d’écoute.

La fonction WskGetLocalAddress est particulièrement utile pour déterminer l’adresse de transport locale spécifique qui a été affectée à un socket par le protocole de transport lorsque le socket était lié à l’adresse générique locale. Pour un socket orienté connexion lié à l’adresse générique locale, l’adresse de transport locale peut ne pas être affectée au socket par le protocole de transport tant que le socket n’est pas connecté à une adresse de transport distante. L’étape où l’adresse de transport locale est affectée au socket dépend du protocole de transport. Pour TCP, le numéro de port est attribué lorsqu’un socket orienté connexion est lié, mais l’adresse IP n’est pas affectée tant que le socket n’est pas connecté.

Si la fonction WskGetLocalAddress retourne STATUS_PENDING, la mémoire tampon vers laquelle pointe le paramètre LocalAddress doit rester valide jusqu’à ce que l’IRP soit terminée. Si l’application WSK a alloué la mémoire tampon avec l’une des fonctions ExAllocateXxx , elle ne peut pas libérer la mémoire avec la fonction ExFreeXxx correspondante tant que l’IRP n’est pas terminée. Si l’application WSK a alloué la mémoire tampon sur la pile, elle ne peut pas retourner à partir de la fonction qui appelle la fonction WskGetLocalAddress tant qu’une fois l’IRP terminée.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible dans Windows Vista et versions ultérieures des systèmes d’exploitation Windows.
Plateforme cible	Universal
En-tête	wsk.h (inclure Wsk.h)
IRQL	<= DISPATCH_LEVEL