PFN_WSK_GET_NAME_INFO fonction de rappel (wsk.h)

Article
02/27/2024

La fonction WskGetNameInfo fournit une traduction indépendante du protocole d’une adresse de transport vers un nom d’hôte.

Syntaxe

PFN_WSK_GET_NAME_INFO PfnWskGetNameInfo;

NTSTATUS PfnWskGetNameInfo(
  [in]            PWSK_CLIENT Client,
  [in]            PSOCKADDR SockAddr,
  [in]            ULONG SockAddrLength,
  [out, optional] PUNICODE_STRING NodeName,
  [out, optional] PUNICODE_STRING ServiceName,
  [in]            ULONG Flags,
  [in, optional]  PEPROCESS OwningProcess,
  [in, optional]  PETHREAD OwningThread,
  [in, out]       PIRP Irp
)
{...}

Paramètres

[in] Client

[in] Pointeur vers une structure WSK_CLIENT qui a été retournée via le paramètre WskProviderNpi du Fonction WskCaptureProviderNPI .

[in] SockAddr

[in] Pointeur vers une structure SOCKADDR qui contient l’adresse IP et le numéro de port du socket.

[in] SockAddrLength

[in] Spécifie la longueur, en octets, de la mémoire tampon pointée vers le paramètre SockAddr . La valeur de SockAddrLength ne doit pas dépasser la taille de la structure SOCKADDR_STORAGE .

[out, optional] NodeName

[out] Pointeur facultatif vers une structure UNICODE_STRING qui contient une chaîne Unicode qui représente un nom d’hôte (nœud). En cas de réussite, le nom d’hôte Unicode est écrit en tant que nom de domaine complet (FQDN) par défaut. L’appelant doit fournir une mémoire tampon UNICODE_STRING suffisamment grande pour contenir le nom d’hôte Unicode, qui inclut le caractère NULL de fin. Si le paramètre NodeBuffer a la valeur NULL, l’appelant ne souhaite pas recevoir de chaîne de nom d’hôte. NodeBuffer et ServiceBuffer ne doivent pas avoir la valeur NULL.

[out, optional] ServiceName

[out] Pointeur facultatif vers une structure UNICODE_STRING qui contient une chaîne Unicode qui représente un nom de service associé au numéro de port. L’appelant doit fournir une mémoire tampon UNICODE_STRING suffisamment grande pour contenir le nom du service Unicode, qui inclut le caractère NULL de fin. Si le paramètre NodeBuffer a la valeur NULL, l’appelant ne souhaite pas recevoir de chaîne de nom de service. NodeBuffer et ServiceBuffer ne doivent pas avoir la valeur NULL.

[in] Flags

[in] Valeur ULONG utilisée pour personnaliser le traitement de cette fonction.

Les indicateurs suivants sont disponibles :

NI_DGRAM

Indique que le service est un service de datagramme. Cet indicateur est nécessaire pour les quelques services qui fournissent des numéros de port différents pour le service UDP et TCP.

NI_NAMEREQD

Indique qu’un nom d’hôte qui ne peut pas être résolu par DNS génère une erreur.

NI_NOFQDN

Résultat qu’un hôte local a uniquement son nom unique (RDN) retourné dans le paramètre NodeName .

NI_NUMERICHOST

Indique que la fonction retourne la forme numérique du nom d’hôte au lieu de son nom, une recherche DNS inversée. La forme numérique du nom d’hôte est également retournée si le nom d’hôte ne peut pas être résolu par DNS.

NI_NUMERICSERV

Indique que la fonction retourne le numéro de port du service au lieu de son nom. En outre, si un nom d’hôte est introuvable pour une adresse IP (127.0.0.2, par exemple), le nom d’hôte est retourné en tant qu’adresse IP.

[in, optional] OwningProcess

[in] Pointeur facultatif vers le processus à partir duquel la fonction récupère le contexte de sécurité. Ce contexte de sécurité indique le contexte du compte d’utilisateur dans lequel la fonction traite la demande de résolution de noms.

Si ce paramètre a la valeur NULL, la fonction traite la demande de résolution de noms dans le contexte d’un compte local prédéfini avec des privilèges minimaux.

Si ce paramètre n’est pas NULL et qu’un jeton d’emprunt d’identité est en vigueur pour le thread appelant, cette fonction échoue et retourne STATUS_INVALID_PARAMETER.

[in, optional] OwningThread

[in] Pointeur facultatif vers le thread à partir duquel la fonction récupère le contexte de sécurité. Ce paramètre peut être non NULL uniquement si OwningProcess n’a pas la valeur NULL. Sinon, cette fonction échoue et retourne STATUS_INVALID_PARAMETER.

Si ce paramètre n’est pas NULL et qu’un jeton d’emprunt d’identité est en vigueur pour le thread appelant, cette fonction échoue et retourne STATUS_INVALID_PARAMETER.

[in, out] Irp

[in/out] Pointeur vers un paquet de demande d’E/S (IRP) à utiliser pour terminer la demande de manière asynchrone. Une fois la demande terminée, Irp ->Iostatus.Information conserve le code status retourné.

Valeur retournée

WskGetNameInfo retourne l’un des codes NTSTATUS suivants :

Code de retour	Description
STATUS_INVALID_PARAMETER	Un paramètre non valide a été spécifié.
STATUS_NO_MATCH	Impossible de résoudre le nom d’hôte.
STATUS_SUCCESS	La fonction s’est terminée avec succès. Si l’application WSK a spécifié un pointeur vers un IRP dans le Paramètre Irp, l’IRP sera terminé avec une status réussie.
STATUS_PENDING	Le sous-système WSK n’a pas pu terminer la fonction immédiatement. Le sous-système WSK termine l’IRP une fois l’opération de contrôle terminée. Le status de l’opération de contrôle sera retourné dans le champ IoStatus.Status de l’IRP.
Autres codes status	Une erreur est survenue. L’IRP sera terminé avec l’échec status.

Remarques

Le processus vers lequel pointe le paramètre OwningProcess , ou le thread vers lequel pointe le processus OwningThread , indique le contexte de sécurité de cette fonction. Le compte d’utilisateur indiqué par le contexte de sécurité indique le contexte de la demande de résolution de noms de la fonction.

Configuration requise

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