Función WNetGetConnectionA (winnetwk.h)

Artículo
08/27/2023

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 usado 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 realiza 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 sección Comentarios que se muestra más adelante.
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 sección Comentarios que se muestra más adelante.
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 pueda pertenecer la conexión.

Comentarios

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 para el dispositivo local asociado. Se produce un error en la función 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 se produzca un error en la llamada a WNetGetConnection , no es suficiente 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 del 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 local 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 bajo 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 . 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, vea Definición de un nombre de dispositivo MS-DOS.

Ejemplos

Para obtener un ejemplo de código que muestra cómo usar la función WNetGetConnection para recuperar el nombre del recurso de red asociado a un dispositivo local, consulte Recuperación del 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 Convenciones para prototipos de función.

Requisitos


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	winnetwk.h
Library	Mpr.lib
Archivo DLL	Mpr.dll