Fonction DhcpRequestParams (dhcpcsdk.h)

Article
08/23/2023

La fonction DhcpRequestParams permet aux appelants d’obtenir de manière synchrone ou de manière synchrone et permanente des données DHCP à partir d’un serveur DHCP.

Syntaxe

DWORD DhcpRequestParams(
  [in]      DWORD                 Flags,
  [in]      LPVOID                Reserved,
  [in]      LPWSTR                AdapterName,
  [in]      LPDHCPCAPI_CLASSID    ClassId,
  [in]      DHCPCAPI_PARAMS_ARRAY SendParams,
  [in, out] DHCPCAPI_PARAMS_ARRAY RecdParams,
  [in]      LPBYTE                Buffer,
  [in, out] LPDWORD               pSize,
  [in]      LPWSTR                RequestIdStr
);

Paramètres

[in] Flags

Indicateurs qui spécifient les données demandées. Ce paramètre est facultatif. Les valeurs possibles suivantes sont prises en charge et ne s’excluent pas mutuellement :

Valeur	Signification
DHCPCAPI_REQUEST_PERSISTENT	La requête est conservée, mais aucune option n’est extraite.
DHCPCAPI_REQUEST_SYNCHRONOUS	Les options seront extraites du serveur.

[in] Reserved

Réservé pour un usage futur. Doit être défini sur NULL.

[in] AdapterName

GUID de l’adaptateur sur lequel les données demandées sont effectuées. Doit comporter moins de 256 caractères.

[in] ClassId

Identificateur de classe (ID) qui doit être utilisé si des messages DHCP INFORM sont transmis sur le réseau. Ce paramètre est facultatif.

[in] SendParams

Données facultatives à demander, en plus des données demandées dans le tableau RecdParams . Le paramètre SendParams ne peut contenir aucune des options standard que le client DHCP envoie par défaut.

[in, out] RecdParams

Tableau de données DHCP que l’appelant souhaite recevoir. Ce tableau doit être vide avant l’appel de la fonction DhcpRequestParams .

[in] Buffer

Mémoire tampon utilisée pour stocker les données associées aux requêtes effectuées dans RecdParams.

[in, out] pSize

Taille de la mémoire tampon.

La taille requise de la mémoire tampon, si elle n’est pas suffisamment dimensionnée pour contenir les données, indique sinon la taille de la mémoire tampon qui a été correctement remplie.

[in] RequestIdStr

Identificateur d’application (ID) utilisé pour faciliter une demande persistante. Doit être une chaîne imprimable sans caractères spéciaux (les virgules, les barres obliques inverses, les deux-points ou d’autres caractères non conformes ne peuvent pas être utilisés). L’identificateur d’application (ID) spécifié est utilisé dans un appel de fonction DhcpUndoRequestParams suivant pour effacer la demande persistante, si nécessaire.

Valeur retournée

Retourne ERROR_SUCCESS en cas de réussite de l’exécution.

Au retour, RecdParams est rempli de pointeurs vers les données demandées, avec les données correspondantes placées dans Buffer. Si pSize indique que Buffer dispose d’un espace insuffisant pour stocker les données retournées, la fonction DhcpRequestParams retourne ERROR_MORE_DATA et retourne la taille de mémoire tampon requise dans pSize. Notez que la taille requise de Buffer peut augmenter pendant le temps qui s’écoule entre le retour de l’appel de fonction initial et un appel suivant ; Par conséquent, la taille requise de Buffer (indiquée dans pSize) fournit une indication de la taille approximative requise de Buffer, plutôt que de garantir que les appels suivants seront retournés correctement si Buffer est défini sur la taille indiquée dans pSize.

D’autres erreurs retournent les codes d’erreur Windows appropriés.

Code de retour	Description
ERROR_INVALID_PARAMETER	Retourné si le paramètre AdapterName contient plus de 256 caractères.
ERROR_BUFFER_OVERFLOW	Retourné si le paramètre AdapterName contient plus de 256 caractères.

Notes

Les clients DHCP stockent les données obtenues à partir d’un serveur DHCP dans leur cache local. Si le cache du client DHCP contient toutes les données demandées dans le tableau RecdParams d’un appel de fonction DhcpRequestParams , le client retourne des données à partir de son cache. Si les données demandées ne sont pas disponibles dans le cache du client, le client traite l’appel de fonction DhcpRequestParams en envoyant un message DHCP-INFORM au serveur DHCP.

Lorsque le client envoie un message DHCP-INFORM au serveur DHCP, il inclut toutes les demandes fournies dans le paramètre SendParams facultatif et fournit l’identificateur de classe (ID) spécifié dans le paramètre ClassId , s’il est fourni.

Les clients peuvent également spécifier que les données DHCP doivent être récupérées à partir du serveur DHCP chaque fois que le client DHCP démarre, ce qui est considéré comme une demande persistante. Pour activer les requêtes persistantes, l’appelant doit spécifier le paramètre RequestIdStr , ainsi que l’indicateur de DHCPAPI_REQUEST_PERSISTENT supplémentaire dans le paramètre dwFlags . Cette fonctionnalité de requête persistante est particulièrement utile lorsque les clients doivent demander automatiquement des informations critiques pour l’application à chaque démarrage. Pour désactiver une demande de persistance, les clients doivent appeler la fonction .

Note Les appelants de cette API ne doivent pas effectuer d’appels bloquants à cette API, car le retour d’un code ou d’une status peut prendre jusqu’à 2 minutes maximum. Les comportements de l’interface utilisateur en particulier ne doivent pas bloquer le retour de cet appel, car cela peut entraîner un retard important dans le temps de réponse de l’interface utilisateur.

Pour plus d’informations sur les messages DHCP INFORM et d’autres informations basées sur des normes sur DHCP, consultez Normes DHCP.

Pour voir la fonction DhcpRequestParams en cours d’utilisation, consultez Exemples DHCP.

Spécifications


Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau \| Applications UWP]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau \| Applications UWP]
Plateforme cible	Windows
En-tête	dhcpcsdk.h
Bibliothèque	Dhcpcsvc.lib
DLL	Dhcpcsvc.dll

Voir aussi

Fonctions DHCP

DHCPCAPI_PARAMS_ARRAY

DhcpCApiInitialize

DhcpUndoRequestParams