Función WNetAddConnectionA (winnetwk.h)

Artículo
08/27/2023

La función WNetAddConnection permite a la aplicación que llama conectar un dispositivo local a un recurso de red. Una conexión correcta es persistente, lo que significa que el sistema restaura automáticamente la conexión durante las operaciones de inicio de sesión posteriores.

Nota Esta función solo se proporciona para la compatibilidad con versiones de 16 bits de Windows. Otras aplicaciones basadas en Windows deben llamar a WNetAddConnection2 o a la función WNetAddConnection3 .

Sintaxis

DWORD WNetAddConnectionA(
  [in] LPCSTR lpRemoteName,
  [in] LPCSTR lpPassword,
  [in] LPCSTR lpLocalName
);

Parámetros

[in] lpRemoteName

Puntero a una cadena terminada en null constante que especifica el recurso de red al que conectarse.

[in] lpPassword

Puntero a una cadena terminada en null constante que especifica la contraseña que se va a usar para realizar una conexión. Este parámetro suele ser la contraseña asociada al usuario actual.

Si este parámetro es NULL, se usa la contraseña predeterminada. Si la cadena está vacía, no se usa ninguna contraseña.

Windows Me/98/95: Este parámetro debe ser NULL o una cadena vacía.

[in] lpLocalName

Puntero a una cadena terminada en null constante que especifica el nombre de un dispositivo local que se va a redirigir, como "F:" o "LPT1". La cadena se trata de forma que no distingue mayúsculas de minúsculas. Si la cadena es NULL, se realiza una conexión al recurso de red sin redirigir el dispositivo local.

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 siguientes valores.

Código devuelto	Descripción
ERROR_ACCESS_DENIED	El autor de la llamada no tiene acceso al recurso de red.
ERROR_ALREADY_ASSIGNED	El dispositivo especificado en el parámetro lpLocalName ya está conectado.
ERROR_BAD_DEV_TYPE	El tipo de dispositivo y el tipo de recurso no coinciden.
ERROR_BAD_DEVICE	El valor especificado en el parámetro lpLocalName no es válido.
ERROR_BAD_NET_NAME	El valor especificado en el parámetro lpRemoteName no es válido o no se puede encontrar.
ERROR_BAD_PROFILE	El perfil de usuario tiene un formato incorrecto.
ERROR_CANNOT_OPEN_PROFILE	El sistema no puede abrir el perfil de usuario para procesar conexiones persistentes.
ERROR_DEVICE_ALREADY_REMEMBERED	Una entrada para el dispositivo especificado en el parámetro lpLocalName ya está en el perfil de usuario.
ERROR_EXTENDED_ERROR	Error específico de la red. Para obtener una descripción del error, llame a la función WNetGetLastError .
ERROR_INVALID_PASSWORD	La contraseña especificada no es válida.
ERROR_NO_NET_OR_BAD_PATH	No se puede realizar la operación porque no se inicia un componente de red o porque no se puede usar un nombre especificado.
ERROR_NO_NETWORK	La red no está disponible.

Comentarios

En Windows Server 2003 y Windows XP, las funciones WNet crean y eliminan letras de unidad de red en el espacio de nombres de dispositivo MS-DOS asociado a una sesión de inicio de sesión porque los dispositivos MS-DOS se identifican mediante AuthenticationID (un
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 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 . La llamada a la función GetLogicalDrives no devuelve letras de unidad de red creadas por llamadas de función de WNet en 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 nombre de dispositivo MS-DOS.

En Windows Server 2003 y Windows XP, si un servicio que se ejecuta como LocalSystem llama a la función WNetAddConnection , la unidad asignada es visible para todas las sesiones de inicio de sesión de usuario.

Nota

El encabezado winnetwk.h define WNetAddConnection 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


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