Función WSASetServiceA (winsock2.h)

Artículo
11/20/2024

La función WSASetService registra o quita del registro una instancia de servicio dentro de uno o varios espacios de nombres.

Sintaxis

INT WSAAPI WSASetServiceA(
  [in] LPWSAQUERYSETA   lpqsRegInfo,
  [in] WSAESETSERVICEOP essoperation,
  [in] DWORD            dwControlFlags
);

Parámetros

[in] lpqsRegInfo

Puntero a la información del servicio para el registro o desregistro.

[in] essoperation

Valor que determina esa 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	Registre el servicio. Para SAP, esto significa enviar una difusión periódica. Se trata de un NOP para el espacio de nombres DNS. En el caso de los almacenes de datos persistentes, esto significa actualizar la información de dirección.
RNRSERVICE_DEREGISTER	Quite el servicio del Registro. Para 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	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 SERVICE_MULTIPLE), solo se eliminará la dirección especificada y debe coincidir exactamente con la estructura de CSADDR_INFO correspondiente que se especificó cuando se registró el servicio.

[in] dwControlFlags

Valor de marca de instalación de servicio que controla aún más la operación realizada de la función WSASetService . Los valores posibles para este parámetro se definen en el archivo de encabezado Winsock2.h.

Bandera	Significado
SERVICE_MULTIPLE	Controla el ámbito de la operación. Cuando no se establece esta marca, las direcciones de servicio se administran como un grupo. Un registro o eliminación del registro invalida todas las direcciones existentes antes de agregar el conjunto de direcciones especificado. Cuando se establece, la acción solo se realiza en el conjunto de direcciones especificado. Un registro no invalida las direcciones existentes y una eliminación del registro solo invalida el conjunto de direcciones especificado.

Bandera

Significado

SERVICE_MULTIPLE

Controla el ámbito de la operación. Cuando no se establece esta marca, las direcciones de servicio se administran como un grupo. Un registro o eliminación del registro invalida todas las direcciones existentes antes de agregar el conjunto de direcciones especificado. Cuando se establece, la acción solo se realiza en el conjunto de direcciones especificado. Un registro no invalida las direcciones existentes y una eliminación del registro solo invalida el conjunto de direcciones especificado.

Valor devuelto

El valor devuelto de WSASetService es cero si la operación se realizó correctamente. De lo contrario, se devuelve el valor SOCKET_ERROR y se puede recuperar un número de error específico llamando a WSAGetLastError.

Código de error	Significado
WSAEACCES	La rutina de llamada no tiene privilegios suficientes para instalar el servicio.
WSAEINVAL	Uno o varios parámetros necesarios no eran válidos o faltaban.
WSANOTINITIALISED	No se ha inicializado el Ws2_32.dll. La aplicación debe llamar primero a WSAStartup antes de llamar a cualquier función de Windows Sockets.
WSA_NOT_ENOUGH_MEMORY	No había memoria suficiente para realizar la operación.

Observaciones

La función WSASetService se puede usar para afectar a un proveedor de espacio de nombres específico, a todos los proveedores asociados a un espacio de nombres específico o a todos los proveedores de todos los espacios de nombres.

Los valores disponibles para essOperation y dwControlFlags combinar para controlar el funcionamiento de la función WSASetService tal como se muestra en la tabla siguiente.

Operación	Banderas	El servicio ya existe	El servicio no existe
RNRSERVICE_REGISTER	Ninguno	Sobrescribe el objeto . Usa solo las direcciones especificadas. El objeto es REGISTERED.	Crea un nuevo objeto. Usa solo las direcciones especificadas. El objeto es REGISTERED.
RNRSERVICE_REGISTER	SERVICE_MULTIPLE	Actualiza el 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	Ninguno	Quita todas las direcciones, pero no quita el objeto del espacio de nombres. El objeto se quita del Registro.	WSASERVICE_NOT_FOUND
RNRSERVICE_DEREGISTER	SERVICE_MULTIPLE	Actualiza el objeto . Quita solo las direcciones especificadas. Solo marca el objeto como DEREGISTERED si no hay ninguna dirección presente. No quita el objeto del espacio de nombres.	WSASERVICE_NOT_FOUND
RNRSERVICE_DELETE	Ninguno	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

La publicación de servicios en directorios, como Los servicios de Active Directory, está restringida en función de las listas de control de acceso (ACL). Para obtener más información, consulte problemas de seguridad para la publicación del servicio.

Cuando el parámetro dwControlFlags se establece en SERVICE_MULTIPLE, una aplicación puede administrar sus direcciones de forma independiente. Esto resulta útil cuando la aplicación quiere 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, puede encontrar que se anula un socket de escucha, pero los demás sockets permanecen operativos. En este caso, el servicio podría quitar la dirección anulada del registro sin afectar a las demás direcciones.

Cuando el parámetro dwControlFlags se establece en SERVICE_MULTIPLE, una aplicación no debe dejar que las direcciones obsoletas permanezcan en el objeto . Esto puede ocurrir si la aplicación anula sin emitir una solicitud DEREGISTER. Cuando se registra un servicio, debe almacenar sus direcciones. En su siguiente invocación, el servicio debe quitar explícitamente estas direcciones obsoletas antiguas del Registro antes de registrar nuevas direcciones.

Nota Si se usan cadenas de caracteres ANSI, es posible que el WSAQUERYSET datos de lpqsRegInfo no contenga ningún resultado después de que esta función devuelva. Esto se debe a que la versión ANSI de este método, WSASetServiceA, convierte los datos ANSI en WSAQUERYSET a Unicode internamente, pero no convierte los resultados en ANSI. Esto afecta principalmente a los transportes que devuelven un "identificador de registro de servicio" que se usa para identificar de forma única un registro. Para solucionar este problema, las aplicaciones deben usar datos de cadena Unicode en WSAQUERYSET al llamar a esta función.

Propiedades del servicio

En la tabla siguiente se describe cómo se representan los datos de propiedad de servicio en una estructura de WSAQUERYSET. Los campos etiquetados como (opcional) pueden contener un puntero nulo.

Miembro WSAQUERYSET	Descripción de la propiedad de servicio
dwSize	Debe establecerse en sizeof (WSAQUERYSET). Se trata de un mecanismo de control de versiones.
dwOutputFlags	No es aplicable ni se omite.
lpszServiceInstanceName	La cadena a la que se hace referencia contiene el nombre de la instancia de servicio.
lpServiceClassId	GUID correspondiente a esta clase de servicio.
lpVersion	(Opcional) Proporciona el número de versión de la instancia de servicio.
lpszComment	(Opcional) Cadena de comentario opcional.
dwNameSpace de	Consulte la tabla siguiente.
lpNSProviderId	Consulte la tabla siguiente.
lpszContext	(Opcional) Especifica el punto inicial de la consulta en un espacio de nombres jerárquico.
dwNumberOfProtocols	Ignorado.
lpafpProtocols	Ignorado.
lpszQueryString	Ignorado.
dwNumberOfCsAddrs	Número de elementos de la matriz de estructuras de CSADDR_INFO a los que hace referencia lpcsaBuffer.
lpcsaBuffer	Puntero a una matriz de estructuras de CSADDR_INFO que contienen las direcciones en las que escucha el servicio.
lpBlob	(Opcional) Se trata de un puntero a una entidad específica del proveedor.

Como se muestra en lo siguiente, la combinación de dwNameSpace y lpNSProviderId miembros determinan que los proveedores de espacios de nombres se ven afectados por esta función.

dwNameSpace de	lpNSProviderId	Ámbito de impacto
Ignorado	No null	Proveedor de espacio de nombres especificado.
Un identificador de espacio de nombre válido	Nulo	Todos los proveedores de espacio de nombres que admiten el espacio de nombres indicado.
NS_ALL	Nulo	Todos los proveedores de espacio de nombres.

Windows Phone 8: La función WSASetServiceW de es compatible con las aplicaciones de la Tienda de Windows Phone en Windows Phone 8 y versiones posteriores.

windows 8.1 y Windows Server 2012 R2: la función WSASetServiceW de es compatible con las aplicaciones de la Tienda Windows en Windows 8.1, Windows Server 2012 R2 y versiones posteriores.

Nota

El encabezado winsock2.h define WSASetService 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 Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows 8.1, Windows Vista [aplicaciones de escritorio \| Aplicaciones para UWP]
servidor mínimo admitido	Windows Server 2003 [aplicaciones de escritorio \| Aplicaciones para UWP]
de la plataforma de destino de	Windows
encabezado de	winsock2.h
biblioteca de	Ws2_32.lib
DLL de	Ws2_32.dll