Función GetServiceA (nspapi.h)

  • Artículo

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 estructuras de datos de NS_SERVICE_INFO .

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, se incluye este material de referencia.
 
Nota Las funciones detalladas en Resolución de nombres independientes del protocolo 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

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
 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
 Nivel NetBIOS a través de 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 acceder 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 las 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 de 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 los datos en el miembro lpComment de las estructuras de datos almacenadas en *lpBuffer.
PROP_LOCALE
 Si se establece esta marca, la función almacena datos en el miembro lpLocale de las estructuras de datos almacenadas en *lpBuffer.
PROP_DISPLAY_HINT
 Si se establece esta marca, la función almacena datos en el miembro dwDisplayHint 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 miembro lpMachineName de las estructuras de datos almacenadas en *lpBuffer.
PROP_ADDRESSES
 Si se establece esta marca, la función almacena datos en el miembro lpServiceAddress 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 e 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 de SERVICE_INFO . Los miembros de estas estructuras de SERVICE_INFO contendrán datos válidos basados en las marcas de bits que se establecen en el parámetro dwProperties . Si la marca de bits correspondiente de un miembro no se establece en dwProperties, el valor del miembro no está definido.

La función almacena las estructuras de 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.

Comentarios

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 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 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado nspapi.h
Library Mswsock.lib
Archivo DLL Mswsock.dll

Consulte también

NS_SERVICE_INFO

SERVICE_INFO

SetService

Funciones winsock

Referencia de Winsock