LPNSPV2SETSERVICEEX función de devolución de llamada (ws2spi.h)

Artículo
08/28/2023

La función NSPv2SetServiceEx registra o anula el registro de un nombre o instancia de servicio dentro de un espacio de nombres de un proveedor de servicios de espacio de nombres versión 2 (NSPv2).

Sintaxis

LPNSPV2SETSERVICEEX Lpnspv2setserviceex;

void Lpnspv2setserviceex(
  [in] HANDLE hAsyncCall,
  [in] LPGUID lpProviderId,
  [in] LPWSAQUERYSET2W lpqsRegInfo,
  [in] WSAESETSERVICEOP essOperation,
  [in] DWORD dwControlFlags,
  [in] LPVOID lpvClientSessionArg
)
{...}

Parámetros

[in] hAsyncCall

Identificador devuelto de la llamada anterior a NSPv2LookupServiceBegin usado para llamadas asincrónicas.

[in] lpProviderId

Puntero al GUID del proveedor de espacios de nombres específico en el que se registra el nombre o el servicio.

[in] lpqsRegInfo

Información de propiedad que se actualizará tras el registro.

[in] essOperation

Tipo de operación solicitada.

Este parámetro puede ser uno de los valores del tipo de enumeración WSAESETSERVICEOP definido en el archivo de encabezado Winsock2.h .

Valor	Significado
RNRSERVICE_REGISTER 0	Registre el servicio. Para el espacio de nombres del Protocolo de publicidad de servicios (SAP) usado en un entorno de NetWare, esto significa enviar una difusión periódica. Se trata de un NOP para el espacio de nombres del Sistema de nombres de dominio (DNS). Para los almacenes de datos persistentes, esto significa actualizar la información de dirección.
RNRSERVICE_DEREGISTER 1	Anule el registro del servicio. Para el espacio de nombres de SAP, esto significa dejar de enviar la difusión periódica. Se trata de un NOP para el espacio de nombres DNS. Para los almacenes de datos persistentes, esto significa eliminar la información de dirección.
RNRSERVICE_DELETE 2	Elimine el servicio del nombre dinámico y los espacios persistentes. En el caso de los servicios representados por varias estructuras de CSADDR_INFO (con la marca de SERVICE_MULTIPLE), solo se eliminará la dirección proporcionada y esto debe coincidir exactamente con la estructura CSADDR_INFO correspondiente proporcionada cuando se registró el servicio.

[in] dwControlFlags

Conjunto de marcas que controla la operación solicitada.

Los valores posibles para este parámetro se definen en el archivo de encabezado Winsock2.h .

Valor	Significado
SERVICE_MULTIPLE 0x00000001	Controlar el ámbito de la operación. Cuando se establece este valor, la acción solo se realiza en el conjunto de direcciones especificado. Una operación de registro no invalida las direcciones existentes y una operación de registro solo invalida el conjunto de direcciones especificado. Cuando este valor no está presente, las direcciones de servicio se administran como un grupo. Un registro o anulación del registro invalida todas las direcciones existentes antes de agregar el conjunto de direcciones especificado.

Valor

Significado

SERVICE_MULTIPLE

0x00000001

Controlar el ámbito de la operación.

Cuando se establece este valor, la acción solo se realiza en el conjunto de direcciones especificado. Una operación de registro no invalida las direcciones existentes y una operación de registro solo invalida el conjunto de direcciones especificado.

Cuando este valor no está presente, las direcciones de servicio se administran como un grupo. Un registro o anulación del registro invalida todas las direcciones existentes antes de agregar el conjunto de direcciones especificado.

[in] lpvClientSessionArg

Puntero a la sesión de cliente.

Valor devuelto

La función debe devolver NO_ERROR (cero) si la rutina se realiza correctamente. Debe devolver SOCKET_ERROR (es decir, 1) si se produce un error en la rutina y debe establecer el código de error adecuado mediante WSASetLastError.

Código de error	Significado
WSA_NOT_ENOUGH_MEMORY	No hay suficiente memoria disponible para realizar esta operación.
WSAEACCES	La rutina de llamada no tiene privilegios suficientes para instalar el servicio.
WSAEINVAL	Uno o varios parámetros no eran válidos o faltaban para este proveedor.
WSAEOPNOTSUPP	La operación no es compatible. Este error se devuelve si el proveedor de espacios de nombres no implementa esta función. Este error también se puede devolver si dwControlCode especificado es un comando no reconocido.
WSASERVICE_NOT_FOUND	El servicio es desconocido. El servicio no se encuentra en el espacio de nombres especificado.

Comentarios

La función NSPv2SetServiceEx se usa como parte de la arquitectura del proveedor de servicios de espacio de nombres versión 2 (NSPv2) disponible en Windows Vista y versiones posteriores.

En Windows Vista y Windows Server 2008, la función NSPv2SetServiceEx solo se puede usar para las operaciones en proveedores de espacios de nombres NS_EMAIL.

La función NSPv2Startup se llama cada vez que un nuevo proceso de cliente comienza a usar el proveedor de espacios de nombres. Los proveedores pueden usar el argumento de sesión de cliente al que apunta el parámetro ppvClientSessionArg para almacenar información sobre esta sesión. Este argumento de sesión de cliente se puede pasar a la función NSPv2SetServiceEx en el parámetro lpvClientSessionArg .

La función NSPv2SetServiceEx es opcional, dependiendo de los requisitos del proveedor NSPv2. Si no se implementa la función NSPv2SetServiceEx , el puntero de función NSPv2 puede ser a una función de código auxiliar que siempre devuelve NO_ERROR.

En la tabla siguiente se muestra la posible combinación de valores para los parámetros essOperation y dwControlFlags .

essOperation	dwControlFlags	El servicio ya existe	El servicio no existe
RNRSERVICE_REGISTER	None	Sobrescribe el objeto . Usa solo direcciones especificadas. El objeto es REGISTERED.	Crea un nuevo objeto. Usa solo direcciones especificadas. El objeto es REGISTERED.
RNRSERVICE_REGISTER	SERVICE_MULTIPLE	Novedades objeto . Agrega nuevas direcciones al conjunto existente. El objeto es REGISTERED.	Crea un nuevo objeto. Usa todas las direcciones especificadas. El objeto es REGISTERED.
RNRSERVICE_DEREGISTER	None	Quita todas las direcciones, pero no quita el objeto del espacio de nombres. El objeto es DEREGISTERED.	WSASERVICE_NOT_FOUND
RNRSERVICE_DEREGISTER	SERVICE_MULTIPLE	Novedades objeto . Quita solo las direcciones especificadas. Marque solo el objeto como DEREGISTERED si no hay direcciones presentes. No quita del espacio de nombres.	WSASERVICE_NOT_FOUND
RNRSERVICE_DELETE	None	Quita el objeto del espacio de nombres.	WSASERVICE_NOT_FOUND
RNRSERVICE_DELETE	SERVICE_MULTIPLE	Quita solo las direcciones especificadas. Solo quita el objeto del espacio de nombres si no quedan direcciones.	WSASERVICE_NOT_FOUND

Cuando el parámetro dwControlFlags se establece en SERVICE_MULTIPLE, esto permite a una aplicación administrar sus direcciones de forma independiente. Esto resulta útil cuando la aplicación debe administrar sus protocolos individualmente o cuando el servicio reside en más de un equipo. Por ejemplo, cuando un servicio usa más de un protocolo, un socket de escucha puede anularse, pero los demás sockets permanecen operativos. En este ejemplo, el servicio podría anular el registro de la dirección anulada sin afectar a las demás direcciones.

Al usar SERVICE_MULTIPLE, una aplicación no debe permitir que las direcciones antiguas permanezcan en el objeto . Esto puede ocurrir si la aplicación anula sin emitir una solicitud de RNRSERVICE_DEREGISTER . Cuando se registra un servicio, debe almacenar sus direcciones. En su siguiente llamada, el servicio debe anular explícitamente estas direcciones antiguas antes de registrar nuevas direcciones.

Si no se implementa la función NSPv2SetServiceEx , se deben interceptar las llamadas a esa función mediante una función de código auxiliar que devuelve WSAEOPNOTSUPP. El puntero de función NSPv2 a la función NSPv2SetServiceEx no implementada en la estructura NSPV2_ROUTINE debe apuntar a la función de código auxiliar.

Propiedades del servicio

En la tabla siguiente se enumeran WSAQUERYSET2 nombres de miembros y se describe cómo se representan los datos de propiedad de servicio. Los miembros etiquetados como opcionales y dependientes de los requisitos del proveedor NSPv2 se pueden proporcionar como puntero **NULL** cuando el proveedor de espacios de nombres no lo está.

WSAQUERYSET2 nombre de miembro	Descripción de la propiedad de servicio
dwSize	Establezca en sizeof(WSAQUERYSET2). Se trata de un mecanismo de control de versiones.
lpszServiceInstanceName	Cadena que contiene el nombre de la instancia de servicio.
lpVersion	Número de versión de la instancia de servicio. Este miembro es opcional, dependiendo de los requisitos del proveedor de servicios NSPv2.
lpszComment	Cadena de comentario. Este miembro es opcional, dependiendo de los requisitos del proveedor de servicios NSPv2.
dwNameSpace	Identificador del espacio de nombres. Este miembro es opcional, dependiendo de los requisitos del proveedor de servicios NSPv2.
lpNSProviderId	Identificador del proveedor. Tenga en cuenta que el identificador del proveedor del espacio de nombres también se pasa en el parámetro lpProviderId . Este miembro es opcional, dependiendo de los requisitos del proveedor de servicios NSPv2.
lpszContext	Punto de partida de la consulta en un espacio de nombres jerárquico. Este miembro es opcional, dependiendo de los requisitos del proveedor de servicios NSPv2.
dwNumberOfProtocols	Tamaño, en bytes, del número de entradas de la matriz de restricciones de protocolo. Este miembro puede ser cero. Este miembro es opcional, dependiendo de los requisitos del proveedor de servicios NSPv2.
lpafpProtocols	Matriz de estructuras AFPROTOCOLS . Este miembro es opcional, dependiendo de los requisitos del proveedor de servicios NSPv2.
lpszQueryString	Algunos espacios de nombres (como whois++) admiten consultas enriquecidas de tipo SQL contenidas en una cadena de texto simple. Este parámetro se usa para especificar esa cadena. Este miembro es opcional, dependiendo de los requisitos del proveedor de servicios NSPv2.
dwNumberOfCsAddrs	Número de elementos de la matriz de estructuras de CSADDR_INFO a las que hace referencia lpcsaBuffer.
lpcsaBuffer	Puntero a una matriz de estructuras de CSADDR_INFO que contienen la dirección o direcciones en las que escucha el servicio.
dwOutputFlags	Este miembro es opcional, dependiendo de los requisitos del proveedor de servicios NSPv2.
lpBlob	Puntero a una entidad específica del proveedor. Este miembro es necesario para el espacio de nombres NS_EMAIL. Este miembro es opcional, dependiendo de los requisitos de otros proveedores de servicios NSPv2.

**Nota** Es aceptable que el miembro **iProtocol** de la estructura CSADDR_INFO contenga la constante de manifiesto **IPROTOCOL_ANY**, que indica un valor comodín. El proveedor de espacios de nombres debe sustituir un valor aceptable para la familia de direcciones y el tipo de socket especificados.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2008 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	ws2spi.h