Compartir a través de


Función WNetAddConnection2A (winnetwk.h)

La función WNetAddConnection2 realiza una conexión a un recurso de red y puede redirigir un dispositivo local al recurso de red.

La función WNetAddConnection2 reemplaza a la función WNetAddConnection . Si puede pasar un identificador a una ventana que el proveedor de recursos de red puede usar como ventana de propietario para los cuadros de diálogo, llame a la función WNetAddConnection3 en su lugar.

Sintaxis

DWORD WNetAddConnection2A(
  [in] LPNETRESOURCEA lpNetResource,
  [in] LPCSTR         lpPassword,
  [in] LPCSTR         lpUserName,
  [in] DWORD          dwFlags
);

Parámetros

[in] lpNetResource

Puntero a una estructura NETRESOURCE que especifica los detalles de la conexión propuesta, como información sobre el recurso de red, el dispositivo local y el proveedor de recursos de red.

Debe especificar los siguientes miembros de la estructura NETRESOURCE .

Miembro Significado
dwType
Tipo de recurso de red al que se va a conectar.

Si el miembro lpLocalName apunta a una cadena no vacía, este miembro puede ser igual a RESOURCETYPE_DISK o RESOURCETYPE_PRINT.

Si lpLocalName es NULL, o si apunta a una cadena vacía, dwType puede ser igual a RESOURCETYPE_DISK, RESOURCETYPE_PRINT o RESOURCETYPE_ANY.

Aunque este miembro es necesario, el proveedor de servicios de red puede omitir su información.

lpLocalName
Puntero a una cadena terminada en null 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 está vacía o si lpLocalName es NULL, la función realiza una conexión al recurso de red sin redirigir un dispositivo local.

lpRemoteName
Puntero a una cadena terminada en null que especifica el recurso de red al que conectarse. La cadena puede tener hasta MAX_PATH caracteres de longitud y debe seguir las convenciones de nomenclatura del proveedor de red.
lpProvider
Puntero a una cadena terminada en null que especifica el proveedor de red al que conectarse.

Si lpProvider es NULL o si apunta a una cadena vacía, el sistema operativo intenta determinar el proveedor correcto mediante el análisis de la cadena a la que apunta el miembro lpRemoteName .

Si este miembro no es NULL, el sistema operativo intenta realizar una conexión solo con el proveedor de red con nombre.

Solo debe establecer este miembro si conoce el proveedor de red que desea usar. De lo contrario, deje que el sistema operativo determine a qué proveedor se asigna el nombre de red.

 

La función WNetAddConnection2 omite los demás miembros de la estructura NETRESOURCE .

[in] lpPassword

Puntero a una cadena terminada en null constante que especifica una contraseña que se va a usar para realizar la conexión de red.

Si lpPassword es NULL, la función usa la contraseña predeterminada actual asociada al usuario especificado por el parámetro lpUserName .

Si lpPassword apunta a una cadena vacía, la función no usa una contraseña.

Si se produce un error en la conexión debido a una contraseña no válida y el valor de CONNECT_INTERACTIVE se establece en el parámetro dwFlags , la función muestra un cuadro de diálogo que pide al usuario que escriba la contraseña.

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

[in] lpUserName

Puntero a una cadena terminada en null constante que especifica un nombre de usuario para realizar la conexión.

Si lpUserName es NULL, la función usa el nombre de usuario predeterminado. (El contexto de usuario del proceso proporciona el nombre de usuario predeterminado).

El parámetro lpUserName se especifica cuando los usuarios quieren conectarse a un recurso de red para el que se les ha asignado un nombre de usuario o una cuenta que no sea el nombre de usuario o la cuenta predeterminados.

La cadena de nombre de usuario representa un contexto de seguridad. Puede ser específico de un proveedor de red.

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

[in] dwFlags

Un conjunto de opciones de conexión. Los valores posibles para las opciones de conexión se definen en el archivo de encabezado Winnetwk.h . Actualmente se pueden usar los valores siguientes.

Value Significado
CONNECT_UPDATE_PROFILE
0x00000001
Se debe recordar la conexión de recursos de red.

Si se establece esta marca de bits, el sistema operativo intenta restaurar automáticamente la conexión cuando el usuario inicia sesión.

El sistema operativo solo recuerda conexiones correctas que redirigen los dispositivos locales. No recuerda las conexiones que no son correctas o sin dispositivo. (Una conexión sin dispositivo se produce cuando el miembro lpLocalName es NULL o apunta a una cadena vacía).

Si esta marca de bits está desactivada, el sistema operativo no intenta restaurar la conexión cuando el usuario inicia sesión.

CONNECT_UPDATE_RECENT
0x00000002
La conexión de recursos de red no debe colocarse en la lista de conexiones recientes.

Si se establece esta marca y la conexión se agrega correctamente, la conexión de recursos de red se colocará en la lista de conexiones recientes solo si tiene un dispositivo local redirigido asociado a él.

CONNECT_TEMPORARY
0x00000004
No se debe recordar la conexión de recursos de red.

Si se establece esta marca, el sistema operativo no intentará restaurar la conexión cuando el usuario vuelva a iniciar sesión.

CONNECT_INTERACTIVE
0x00000008
Si se establece esta marca, el sistema operativo puede interactuar con el usuario con fines de autenticación.
CONNECT_PROMPT
0x00000010
Esta marca indica al sistema que no use ninguna configuración predeterminada para nombres de usuario o contraseñas sin ofrecer al usuario la oportunidad de proporcionar una alternativa. Esta marca se omite a menos que también se establezca CONNECT_INTERACTIVE.
CONNECT_REDIRECT
0x00000080
Esta marca fuerza el redireccionamiento de un dispositivo local al realizar la conexión.

Si el miembro lpLocalName de NETRESOURCE especifica un dispositivo local para redirigir, esta marca no tiene ningún efecto, ya que el sistema operativo sigue intentando redirigir el dispositivo especificado. Cuando el sistema operativo elige automáticamente un dispositivo local, el miembro dwType no debe ser igual a RESOURCETYPE_ANY.

Si no se establece esta marca, se elige automáticamente un dispositivo local para el redireccionamiento solo si la red requiere que se redirija un dispositivo local.

Windows Server 2003 y Windows XP: Cuando el sistema asigna automáticamente letras de unidad de red, las letras se asignan a partir de Z:, Y:, y finalizan con C:. Esto reduce la colisión entre letras de unidad por inicio de sesión (como letras de unidad de red) y letras de unidad globales (como unidades de disco). Tenga en cuenta que las versiones anteriores de las letras de unidad asignadas de Windows a partir de C: y que terminan con Z:.

CONNECT_CURRENT_MEDIA
0x00000200
Si se establece esta marca, el sistema operativo no empieza a usar un nuevo medio para intentar establecer la conexión (iniciar una nueva conexión de marcado, por ejemplo).
CONNECT_COMMANDLINE
0x00000800
Si se establece esta marca, el sistema operativo solicita al usuario la autenticación mediante la línea de comandos en lugar de una interfaz gráfica de usuario (GUI). Esta marca se omite a menos que también se establezca CONNECT_INTERACTIVE.

Windows XP: Este valor se admite en Windows XP y versiones posteriores.

CONNECT_CMD_SAVECRED
0x00001000
Si se establece esta marca y el sistema operativo solicita una credencial, el administrador de credenciales debe guardar la credencial. Si el administrador de credenciales está deshabilitado para la sesión de inicio de sesión del autor de la llamada o si el proveedor de red no admite el guardado de credenciales, se omite esta marca. Esta marca se omite a menos que también se establezca CONNECT_INTERACTIVE. Esta marca también se omite a menos que establezca la marca de CONNECT_COMMANDLINE.

Windows XP: Este valor se admite en Windows XP y versiones posteriores.

CONNECT_CRED_RESET
0x00002000
Si se establece esta marca y el sistema operativo solicita una credencial, el administrador de credenciales restablece la credencial. Si el administrador de credenciales está deshabilitado para la sesión de inicio de sesión del autor de la llamada o si el proveedor de red no admite el guardado de credenciales, se omite esta marca. Esta marca también se omite a menos que establezca la marca CONNECT_COMMANDLINE.

Windows Vista: Este valor se admite en Windows Vista y versiones posteriores.

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 puede ser uno de los siguientes códigos de error o uno de los códigos de error del sistema.

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 local especificado por el miembro lpLocalName ya está conectado a un recurso de red.
ERROR_BAD_DEV_TYPE
El tipo de dispositivo local y el tipo de recurso de red no coinciden.
ERROR_BAD_DEVICE
El nombre de dispositivo especificado no es válido. Este error se devuelve si el miembro lpLocalName de la estructura NETRESOURCE a la que apunta el parámetro lpNetResource especifica un dispositivo que no se puede redirigir.
ERROR_BAD_NET_NAME
No se encuentra el nombre de red especificado. Este valor se devuelve si el miembro lpRemoteName de la estructura NETRESOURCE a la que apunta el parámetro lpNetResource especifica un recurso que no es aceptable para ningún proveedor de recursos de red, ya sea porque el nombre del recurso está vacío, no es válido o porque no se puede encontrar el recurso con nombre.
ERROR_BAD_PROFILE
El perfil de usuario tiene un formato incorrecto.
ERROR_BAD_PROVIDER
El nombre del proveedor de red especificado no es válido. Este error se devuelve si el miembro lpProvider de la estructura NETRESOURCE a la que apunta el parámetro lpNetResource especifica un valor que no coincide con ningún proveedor de red.
ERROR_BAD_USERNAME
El nombre de usuario especificado no es válido.
ERROR_BUSY
El enrutador o proveedor está ocupado, posiblemente inicializando. El autor de la llamada debe reintentar.
ERROR_CANCELLED
El usuario canceló el intento de realizar la conexión a través de un cuadro de diálogo de uno de los proveedores de recursos de red o mediante un recurso llamado.
ERROR_CANNOT_OPEN_PROFILE
El sistema no puede abrir el perfil de usuario para procesar conexiones persistentes.
ERROR_DEVICE_ALREADY_REMEMBERED
El nombre del dispositivo local tiene una conexión recordada a otro recurso de red. Este error se devuelve si una entrada para el dispositivo especificado por el miembro lpLocalName de la estructura NETRESOURCE a la que apunta el parámetro lpNetResource especifica un valor que ya está en el perfil de usuario para una conexión diferente a la especificada en el parámetro lpNetResource .
ERROR_EXTENDED_ERROR
Error específico de la red. Llame a la función WNetGetLastError para obtener una descripción del error.
ERROR_INVALID_ADDRESS
Se intentó acceder a una dirección no válida. Este error se devuelve si el parámetro dwFlags especifica un valor de CONNECT_REDIRECT, pero no se especificó el miembro lpLocalName de la estructura NETRESOURCE a la que apunta el parámetro lpNetResource .
ERROR_INVALID_PARAMETER
Un parámetro es incorrecto. Este error se devuelve si el miembro dwType de la estructura NETRESOURCE a la que apunta el parámetro lpNetResource especifica un valor distinto de RESOURCETYPE_DISK, RESOURCETYPE_PRINT o RESOURCETYPE_ANY. Este error también se devuelve si el parámetro dwFlags especifica un valor incorrecto o desconocido.
ERROR_INVALID_PASSWORD
La contraseña especificada no es válida y no se establece la marca CONNECT_INTERACTIVE.
ERROR_LOGON_FAILURE
Error de inicio de sesión debido a un nombre de usuario desconocido o una contraseña incorrecta.
ERROR_NO_NET_OR_BAD_PATH
Ningún proveedor de red aceptó la ruta de acceso de red especificada. Este error se devuelve si ningún proveedor de red reconoce el miembro lpRemoteName de la estructura NETRESOURCE a la que apunta el parámetro lpNetResource .
ERROR_NO_NETWORK
La red no está disponible.
Otros
Use FormatMessage para obtener la cadena de mensaje del error devuelto.

Comentarios

En Windows Server 2003 y Windows XP, las funciones WNet crean y eliminan letras de unidad de red en el espacio de nombres del 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 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 . La llamada a la función GetLogicalDrives no devuelve letras de unidad de red creadas por llamadas de 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.

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

Para los proveedores de red de Microsoft, el miembro lpRemoteName de la estructura NETRESOURCE a la que apunta el parámetro lpNetResource puede contener una dirección IPv4 en notación decimal de puntos. Un ejemplo de un recurso compartido podría ser el siguiente:

\192.168.1.1\share

Para los proveedores de red de Microsoft en Windows Vista y versiones posteriores, el miembro lpRemoteName de la estructura NETRESOURCE a la que apunta el parámetro lpNetResource puede contener una dirección IPv6. Sin embargo, se debe usar el formato literal IPv6 para que la dirección IPv6 se analice correctamente. Una dirección literal IPv6 tiene el formato:

Dirección ipv6 con los caracteres ':' reemplazados por caracteres '-' seguidos de la cadena ".ipv6-literal.net".

Por ejemplo, para la siguiente dirección IPv6:

2001:4898:9:3:c069:aa97:fe76:2449

Un ejemplo de un recurso compartido podría ser el siguiente:

\2001-4898-9-3-c069-aa97-fe76-2449.ipv6-literal.net\share

Otros proveedores de red pueden admitir el miembro lpRemoteName de la estructura NETRESOURCE a la que apunta el parámetro lpNetResource que contiene una dirección IPv4 o IPv6, pero esto es un proveedor de red específico.

Windows 7 y Windows Server 2008 R2: Si se llama a la función WNetAddConnection2 con credenciales de usuario explícitas especificadas en pUsername y lpPassword para establecer una conexión con un recurso de red en un servidor específico y, a continuación, se llama de nuevo con cualquiera de estos parámetros como NULL (para usar el nombre de usuario predeterminado o la contraseña predeterminada) en el mismo servidor, se produce un error en la llamada. El error devuelto se ERROR_BAD_USERNAME o ERROR_INVALID_PASSWORD.

Ejemplos

En el ejemplo de código siguiente se muestra cómo usar la función WNetAddConnection2 para establecer la conexión a un recurso de red.

#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "mpr.lib")

#include <windows.h>
#include <tchar.h>
#include <stdio.h>
#include <Winnetwk.h>

// Need to link with Netapi32.lib and Mpr.lib

int wmain(int argc, wchar_t * argv[])
{

    DWORD dwRetVal;

    NETRESOURCE nr;
    DWORD dwFlags;

    if (argc != 5) {
        wprintf(L"Usage: %s <localname> <remotename> <username> <password>\n",
                argv[0]);
        wprintf(L"       %s X: \\\\contoso\\public testuser testpasswd\n",
                argv[0]);
        exit(1);
    }

    wprintf(L"Calling WNetAddConnection2 with\n");
    wprintf(L"  lpLocalName = %s\n", argv[1]);
    wprintf(L"  lpRemoteName = %s\n", argv[2]);
    wprintf(L"  lpUsername = %s\n", argv[3]);
    wprintf(L"  lpPassword = %s\n", argv[4]);

// Zero out the NETRESOURCE struct
    memset(&nr, 0, sizeof (NETRESOURCE));

// Assign our values to the NETRESOURCE structure.

    nr.dwType = RESOURCETYPE_ANY;
    nr.lpLocalName = argv[1];
    nr.lpRemoteName = argv[2];
    nr.lpProvider = NULL;

// Assign a value to the connection options
    dwFlags = CONNECT_UPDATE_PROFILE;
//
// Call the WNetAddConnection2 function to assign
//   a drive letter to the share.
//
    dwRetVal = WNetAddConnection2(&nr, argv[4], argv[3], dwFlags);
//
// If the call succeeds, inform the user; otherwise,
//  print the error.
//
    if (dwRetVal == NO_ERROR)
        wprintf(L"Connection added to %s\n", nr.lpRemoteName);
    else
        wprintf(L"WNetAddConnection2 failed with error: %u\n", dwRetVal);

    exit(1); 
}


Para ver otros ejemplos de código que muestran cómo establecer una conexión a un recurso de red mediante la función WNetAddConnection2 , vea Agregar una conexión de red y Asignar una unidad a un recurso compartido.

Nota

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

Consulte también

NETRESOURCE

WNetAddConnection3

WNetCancelConnection2

WNetGetConnection

Información general sobre redes de Windows (WNet)

Funciones de redes de Windows