Función SetAddrInfoExA (ws2tcpip.h)
La función SetAddrInfoEx registra o anula el registro de un nombre, un nombre de servicio y direcciones asociadas a un proveedor de espacios de nombres específico.
Sintaxis
INT WSAAPI SetAddrInfoExA(
[in] PCSTR pName,
[in] PCSTR pServiceName,
[in, out] SOCKET_ADDRESS *pAddresses,
[in] DWORD dwAddressCount,
[in, optional] LPBLOB lpBlob,
[in] DWORD dwFlags,
[in] DWORD dwNameSpace,
[in, optional] LPGUID lpNspId,
[in, optional] timeval *timeout,
[in, optional] LPOVERLAPPED lpOverlapped,
[in, optional] LPLOOKUPSERVICE_COMPLETION_ROUTINE lpCompletionRoutine,
[out, optional] LPHANDLE lpNameHandle
);
Parámetros
[in] pName
Puntero a una cadena terminada en NULL que contiene un nombre en el que las direcciones se van a registrar o anular el registro. La interpretación de este parámetro específico del proveedor de espacios de nombres.
[in] pServiceName
Puntero a una cadena opcional terminada en NULL que contiene el nombre del servicio asociado al nombre que se está registrando. La interpretación de este parámetro es específica del proveedor de espacios de nombres.
[in, out] pAddresses
Puntero a una lista opcional de direcciones para registrarse con el proveedor de espacios de nombres.
[in] dwAddressCount
Número de direcciones pasadas en el parámetro pAddresses . Si este parámetro es cero, el parámetro pName se anula del registro del proveedor de espacios de nombres.
[in, optional] lpBlob
Puntero opcional a los datos que se usan para establecer información de espacio de nombres específica del proveedor asociada al parámetro pName más allá de una lista de direcciones. Cualquier información que no se pueda pasar en el parámetro pAddresses se puede pasar en el parámetro lpBlob . El formato de esta información es específico del proveedor de espacios de nombres.
[in] dwFlags
Conjunto de marcas que controlan cómo se van a registrar los parámetros pName y pServiceName con el proveedor de espacios de nombres. La interpretación de esta información es específica del proveedor de espacios de nombres.
[in] dwNameSpace
Identificador de espacio de nombres con el que se determina el proveedor de espacios de nombres con el que se va a registrar esta información. Si se pasa un identificador de espacio de nombres específico, solo se registrará esta información con los proveedores de espacios de nombres que admiten el espacio de nombres especificado. Si se especifica NS_ALL, se registrará la información con todos los proveedores de espacios de nombres instalados y activos.
Las opciones del parámetro dwNameSpace se muestran en el archivo de inclusión Winsock2.h . Varios proveedores de espacios de nombres se incluyen con Windows Vista y versiones posteriores. Se pueden instalar otros proveedores de espacios de nombres, por lo que los siguientes valores posibles son solo los disponibles con frecuencia. Muchos otros son posibles.
[in, optional] lpNspId
Puntero a un GUID opcional de un proveedor de espacio de nombres específico con el que registrar esta información en el caso de que varios proveedores de espacios de nombres se registren en un único espacio de nombres, como NS_DNS. Si se pasa el GUID de un proveedor de espacio de nombres específico, la información que se registra solo con el proveedor de espacios de nombres especificado. Se puede llamar a la función WSAEnumNameSpaceProviders para recuperar el GUID de un proveedor de espacios de nombres.
[in, optional] timeout
Parámetro opcional que indica el tiempo, en milisegundos, para esperar una respuesta del proveedor de espacios de nombres antes de anular la llamada. Este parámetro está reservado actualmente y debe establecerse en NULL , ya que no se admite una opción de tiempo de espera .
[in, optional] lpOverlapped
Puntero opcional a una estructura superpuesta utilizada para la operación asincrónica. Este parámetro está reservado actualmente y debe establecerse en NULL , ya que no se admiten operaciones asincrónicas.
[in, optional] lpCompletionRoutine
Puntero opcional a una función que se va a invocar después de completarse correctamente para las operaciones asincrónicas. Este parámetro está reservado actualmente y debe establecerse en NULL , ya que no se admiten operaciones asincrónicas.
[out, optional] lpNameHandle
Puntero opcional que solo se usa para operaciones asincrónicas. Este parámetro está reservado actualmente y debe establecerse en NULL , ya que no se admiten operaciones asincrónicas.
Valor devuelto
Si se ejecuta correctamente, SetAddrInfoEx devuelve NO_ERROR (0). Error devuelve un código de error de Windows Sockets distinto de cero, como se encuentra en los códigos de error de Windows Sockets.
Código de error | Significado |
---|---|
Debe producirse una llamada WSAStartup correcta antes de usar esta función. | |
Error temporal en la resolución de nombres. | |
Se proporcionó un parámetro no válido. Este error se devuelve si alguno de los parámetros reservados no es NULL. | |
No hay suficiente espacio en búfer disponible. | |
Error irrecuperable en la resolución de nombres. | |
Error de asignación de memoria. |
Comentarios
La función SetAddrInfoEx proporciona un método independiente del protocolo para registrar o anular el registro de un nombre y una o varias direcciones con un proveedor de espacios de nombres. El proveedor de espacio de nombres NS_EMAIL en Windows Vista y versiones posteriores admite el registro y la desregistración de direcciones. El NS_DNS predeterminado, la NS_PNRPNAME y los proveedores de espacios de nombres NS_PNRPNAME no admiten actualmente el registro de nombres.
Si se llama a la función SetAddrInfoEx con NS_ALL establecido como parámetro dwNameSpace y el parámetro lpNspId no especificado, SetAddrInfoEx intentará registrar o anular el registro del nombre y las direcciones asociadas con todos los espacios de nombres instalados y activos. La función SetAddrInfoEx devolverá éxito si alguno de los proveedores de espacios de nombres registró o anule correctamente el registro del nombre, pero no habrá ninguna indicación de qué proveedor de espacio de nombres se realizó correctamente o cuál de ellos produjo un error en la solicitud.
Cuando se define UNICODE o _UNICODE , SetAddrInfoEx se define en SetAddrInfoExW, la versión Unicode de esta función. Los parámetros de cadena se definen en el tipo de datos PWSTR .
Cuando no se define UNICODE o _UNICODE , SetAddrInfoEx se define en SetAddrInfoExA, la versión ANSI de esta función. Los parámetros de cadena son del tipo de datos PCSTR .
La información registrada con un proveedor de espacios de nombres se puede devolver llamando a las funciones GetAddrInfoEx, getaddrinfo o GetAddrInfoW . La función GetAddrInfoEx es una versión mejorada de las funciones getaddrinfo y GetAddrInfoW .
En Windows Vista y versiones posteriores, cuando se llama a SetAddrInfoEx desde un servicio, si la operación es el resultado de un proceso de usuario que llama al servicio, el servicio debe suplantar al usuario. Esto es para permitir que se apliquen correctamente los compartimientos de seguridad y enrutamiento.
Windows 8.1 y Windows Server 2012 R2: la función SetAddrInfoExW es compatible con las aplicaciones de la Tienda Windows en Windows 8.1, Windows Server 2012 R2 y versiones posteriores.
Nota
El encabezado ws2tcpip.h define SetAddrInfoEx como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.
Requisitos
Requisito | Value |
---|---|
Cliente mínimo compatible | Windows 8.1, Windows Vista [aplicaciones de escritorio | Aplicaciones para UWP] |
Servidor mínimo compatible | Windows Server 2008 [aplicaciones de escritorio | aplicaciones para UWP] |
Plataforma de destino | Windows |
Encabezado | ws2tcpip.h |
Library | Ws2_32.lib |
Archivo DLL | Ws2_32.dll |