Función GetServiceA (nspapi.h)

Artículo
11/20/2024

La función GetService recupera información sobre un servicio de red en el contexto de un conjunto de espacios de nombres predeterminados o un espacio de nombres especificado. El servicio de red se especifica por su tipo y nombre. La información sobre el servicio se obtiene como un conjunto de NS_SERVICE_INFO estructuras de datos.

Nota La función GetService es una extensión específica de Microsoft para la especificación de Windows Sockets 1.1. Esta función está obsoleta. Para mayor comodidad de los desarrolladores de Windows Sockets 1.1, este material de referencia se incluye.

Nota Las funciones detalladas en Protocol-Independent resolución de nombres proporcionan una funcionalidad equivalente en Windows Sockets 2.

Sintaxis

INT GetServiceA(
  [in]           DWORD                dwNameSpace,
  [in]           LPGUID               lpGuid,
  [in]           LPSTR                lpServiceName,
  [in]           DWORD                dwProperties,
  [out]          LPVOID               lpBuffer,
  [in, out]      LPDWORD              lpdwBufferSize,
  [in, optional] LPSERVICE_ASYNC_INFO lpServiceAsyncInfo
);

Parámetros

[in] dwNameSpace

El espacio de nombres, o un conjunto de espacios de nombres predeterminados, que el sistema operativo debe consultar para obtener información sobre el servicio de red especificado.

Use una de las siguientes constantes para especificar un espacio de nombres.

Valor	Significado
NS_DEFAULT	Un conjunto de espacios de nombres predeterminados. El sistema operativo consulta cada espacio de nombres dentro de este conjunto. El conjunto de espacios de nombres predeterminados normalmente incluye todos los espacios de nombres instalados en el sistema. Sin embargo, los administradores del sistema pueden excluir espacios de nombres concretos del conjunto. NS_DEFAULT es el valor que la mayoría de las aplicaciones deben usar para dwNameSpace.
NS_DNS	Sistema de nombres de dominio usado en Internet para la resolución de nombres de host.
NS_NETBT	NetBIOS a través de la capa TCP/IP. Todos los sistemas operativos registran sus nombres de equipo con NetBIOS. Este espacio de nombres se usa para resolver un nombre de equipo en una dirección IP mediante este registro. Tenga en cuenta que NS_NETBT puede acceder a un servidor WINS para realizar la resolución.
NS_SAP	Protocolo de publicidad del servicio NetWare. Esto puede tener acceso a la enlazadora de NetWare si procede. NS_SAP es un espacio de nombres dinámico que permite el registro de servicios.
NS_TCPIP_HOSTS	Busca nombres de host y direcciones IP en el <archivo systemroot>\system32\drivers\etc\hosts.
NS_TCPIP_LOCAL	Mecanismos de resolución de nombres TCP/IP locales, incluidas las comparaciones con el nombre de host local y busca nombres de host y direcciones IP en la memoria caché del host en asignaciones de direcciones IP.

La mayoría de las llamadas a GetService deben usar el valor especial NS_DEFAULT. Esto permite a un cliente obtener sin conocer los espacios de nombres disponibles en un trabajo de Internet. El administrador del sistema determina el acceso al espacio de nombres. Los espacios de nombres pueden venir y pasar sin que el cliente tenga que tener en cuenta los cambios.

[in] lpGuid

Puntero a un identificador único global (GUID) que especifica el tipo del servicio de red. El archivo de encabezado Svcguid.h incluye tipos de servicio GUID de muchos servicios conocidos dentro de los espacios de nombres DNS y SAP.

El archivo de encabezado Svcguid. h no se incluye automáticamente en el archivo de encabezado Winsock2.h.

[in] lpServiceName

Puntero a una cadena terminada en cero que representa de forma única el nombre del servicio. Por ejemplo, "MY SNA SERVER".

[in] dwProperties

Conjunto de marcas de bits que especifican la información del servicio que recupera la función. Cada una de estas constantes de marca de bits, distintas de PROP_ALL, corresponde a un miembro determinado de la estructura de datos SERVICE_INFO. Si se establece la marca, la función coloca información en el miembro correspondiente de las estructuras de datos almacenadas en *lpBuffer. Se definen las marcas de bits siguientes.

Valor	Significado
PROP_COMMENT	Si se establece esta marca, la función almacena datos en el lpComment miembro de las estructuras de datos almacenadas en *lpBuffer.
PROP_LOCALE	Si se establece esta marca, la función almacena datos en el lpLocale miembro de las estructuras de datos almacenadas en *lpBuffer.
PROP_DISPLAY_HINT	Si se establece esta marca, la función almacena datos en el dwDisplayHint miembro de las estructuras de datos almacenadas en *lpBuffer.
PROP_VERSION	Si se establece esta marca, la función almacena datos en el miembro dwVersion de las estructuras de datos almacenadas en *lpBuffer.
PROP_START_TIME	Si se establece esta marca, la función almacena datos en el miembro dwTime de las estructuras de datos almacenadas en *lpBuffer.
PROP_MACHINE	Si se establece esta marca, la función almacena datos en el lpMachineName miembro de las estructuras de datos almacenadas en *lpBuffer.
PROP_ADDRESSES	Si se establece esta marca, la función almacena datos en el lpServiceAddress miembro de las estructuras de datos almacenadas en *lpBuffer.
PROP_SD	Si se establece esta marca, la función almacena datos en el miembro ServiceSpecificInfo de las estructuras de datos almacenadas en *lpBuffer.
PROP_ALL	Si se establece esta marca, la función almacena datos en todos los miembros de las estructuras de datos almacenadas en *lpBuffer.

[out] lpBuffer

Puntero a un búfer para recibir una matriz de estructuras de NS_SERVICE_INFO y información de servicio asociada. Cada estructura de NS_SERVICE_INFO contiene información de servicio en el contexto de un espacio de nombres determinado. Tenga en cuenta que si dwNameSpace es NS_DEFAULT, la función almacena más de una estructura en el búfer; de lo contrario, solo se almacena una estructura.

Cada estructura de NS_SERVICE_INFO contiene una estructura SERVICE_INFO. Los miembros de estas estructuras de SERVICE_INFO contendrán datos válidos basados en las marcas de bits establecidas en el parámetro dwProperties. Si la marca de bits correspondiente de un miembro no está establecida en dwProperties, el valor del miembro no está definido.

La función almacena las estructuras NS_SERVICE_INFO en una matriz consecutiva, comenzando al principio del búfer. Los punteros de las estructuras SERVICE_INFO contenidas apuntan a información almacenada en el búfer entre el final de las estructuras de NS_SERVICE_INFO y el final del búfer.

[in, out] lpdwBufferSize

Puntero a una variable que, en la entrada, contiene el tamaño, en bytes, del búfer al que apunta lpBuffer. En la salida, esta variable contiene el número de bytes necesarios para almacenar la información solicitada. Si este valor de salida es mayor que el valor de entrada, se produjo un error en la función debido a un tamaño de búfer insuficiente.

[in, optional] lpServiceAsyncInfo

Reservado para uso futuro. Debe establecerse en NULL.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es el número de estructuras de NS_SERVICE_INFO almacenadas en *lpBuffer. Cero indica que no se almacenaron estructuras.

Si se produce un error en la función, el valor devuelto es SOCKET_ERROR ( – 1). Para obtener información de error extendida, llame a GetLastError, que devuelve uno de los siguientes valores de error extendidos.

Código de error	Significado
ERROR_INSUFFICIENT_BUFFER	El búfer al que apunta lpBuffer es demasiado pequeño para recibir toda la información solicitada. Llame a la función con un búfer al menos tan grande como el valor devuelto en *lpdwBufferSize.
ERROR_SERVICE_NOT_FOUND	No se encontró el servicio especificado o el espacio de nombres especificado no está en uso. El valor devuelto de la función es cero en este caso.

Observaciones

Nota

El encabezado nspapi.h define GetService 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 2000 Professional [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows 2000 Server [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	nspapi.h
biblioteca de	Mswsock.lib
DLL de	Mswsock.dll

Consulte también

de referencia de Winsock

Compartir a través de