Función WNetGetConnectionA (winnetwk.h)

Artículo
11/20/2024

La función WNetGetConnection recupera el nombre del recurso de red asociado a un dispositivo local.

Sintaxis

DWORD WNetGetConnectionA(
  [in]      LPCSTR  lpLocalName,
  [out]     LPSTR   lpRemoteName,
  [in, out] LPDWORD lpnLength
);

Parámetros

[in] lpLocalName

Puntero a una cadena terminada en NULL constante que especifica el nombre del dispositivo local para el que se obtiene el nombre de red.

[out] lpRemoteName

Puntero a una cadena terminada en null que recibe el nombre remoto que se usa para realizar la conexión.

[in, out] lpnLength

Puntero a una variable que especifica el tamaño del búfer al que apunta el parámetro lpRemoteName, en caracteres. Si se produce un error en la función porque el búfer no es lo suficientemente grande, este parámetro devuelve el tamaño de búfer necesario.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es NO_ERROR.

Si se produce un error en la función, el valor devuelto es un código de error del sistema , como uno de los valores siguientes.

Código devuelto	Descripción
ERROR_BAD_DEVICE	La cadena a la que apunta el parámetro lpLocalName no es válida.
ERROR_NOT_CONNECTED	El dispositivo especificado por lpLocalName no es un dispositivo redirigido. Para obtener más información, vea la siguiente sección Comentarios.
ERROR_MORE_DATA	El búfer es demasiado pequeño. El parámetro lpnLength apunta a una variable que contiene el tamaño de búfer necesario. Hay más entradas disponibles con llamadas posteriores.
ERROR_CONNECTION_UNAVAIL	El dispositivo no está conectado actualmente, pero es una conexión persistente. Para obtener más información, vea la siguiente sección Comentarios.
ERROR_NO_NETWORK	La red no está disponible.
ERROR_EXTENDED_ERROR	Error específico de la red. Para obtener una descripción del error, llame a la función WNetGetLastError.
ERROR_NO_NET_OR_BAD_PATH	Ninguno de los proveedores reconoce el nombre local como tener una conexión. Sin embargo, la red no está disponible para al menos un proveedor al que puede pertenecer la conexión.

Observaciones

Si la conexión de red se realizó mediante la red de Microsoft LAN Manager y la aplicación que realiza la llamada se ejecuta en una sesión de inicio de sesión diferente a la aplicación que realizó la conexión, se producirá un error en una llamada a la función WNetGetConnection del dispositivo local asociado. Se produce un error en la función con ERROR_NOT_CONNECTED o ERROR_CONNECTION_UNAVAIL. Esto se debe a que una conexión realizada con Microsoft LAN Manager solo es visible para las aplicaciones que se ejecutan en la misma sesión de inicio de sesión que la aplicación que realizó la conexión. (Para evitar que la llamada a WNetGetConnection no sea suficiente para que la aplicación se ejecute en la cuenta de usuario que creó la conexión).

Windows Server 2003 y Windows XP: Esta función consulta los espacios de nombres de dispositivo MS-DOS asociados a una sesión de inicio de sesión porque los dispositivos MS-DOS se identifican mediante AuthenticationID. (Un AuthenticationID es el identificador único localmente, o LUID, asociado a una sesión de inicio de sesión). Esto puede afectar a las aplicaciones que llaman a una de las funciones de WNet para crear una letra de unidad de red en un inicio de sesión de usuario, pero consultar las letras de unidad de red existentes en un inicio de sesión de usuario diferente. Un ejemplo de esta situación podría ser cuando se crea el segundo inicio de sesión de un usuario en una sesión de inicio de sesión, por ejemplo, llamando a la función CreateProcessAsUser y el segundo inicio de sesión ejecuta una aplicación que llama a la función getLogicalDrives de . GetLogicalDrives no devuelve letras de unidad de red creadas por una función WNet bajo el primer inicio de sesión. Tenga en cuenta que en el ejemplo anterior todavía existe la primera sesión de inicio de sesión y el ejemplo podría aplicarse a cualquier sesión de inicio de sesión, incluida una sesión de Terminal Services. Para obtener más información, consulte Definición de un MS-DOS nombre de dispositivo.

Ejemplos

Para obtener un ejemplo de código que muestra cómo usar la función WNetGetConnection de para recuperar el nombre del recurso de red asociado a un dispositivo local, vea Recuperar el nombre de conexión.

Nota

El encabezado winnetwk.h define WNetGetConnection 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	winnetwk.h
biblioteca de	Mpr.lib
DLL de	Mpr.dll