Función WSASetServiceA (winsock2.h)

Artículo
08/27/2023

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 la desregistración.

[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

El valor de las marcas 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 .

Marca	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.

Marca

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.

Comentarios

La función WSASetService se puede usar para afectar a un proveedor de espacios 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 se combinan para controlar el funcionamiento de la función WSASetService , como se muestra en la tabla siguiente.

Operación	Marcas	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	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	None	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	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

La publicación de servicios en directorios, como 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 es ú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 permitir 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, existe la posibilidad de que los datos WSAQUERYSET de lpqsRegInfo no contengan 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 en Unicode internamente, pero no convierte los resultados en ANSI. Esto afecta principalmente a los transportes que devuelven un "identificador de registros 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 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	Vea la tabla siguiente.
lpNSProviderId	Vea 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 las 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 los miembros dwNameSpace y lpNSProviderId determinan que los proveedores de espacios de nombres se ven afectados por esta función.

dwNameSpace	lpNSProviderId	Ámbito del impacto
Omitido	Distinto de null	Proveedor de espacio de nombres especificado.
Un identificador de espacio válido	Null	Todos los proveedores de espacio de nombres que admiten el espacio de nombres indicado.
NS_ALL	Null	Todos los proveedores de espacio de nombres.

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

Windows 8.1 y Windows Server 2012 R2: la función WSASetServiceW 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 neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en 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 2003 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	winsock2.h
Library	Ws2_32.lib
Archivo DLL	Ws2_32.dll