Función WNetAddConnection3A (winnetwk.h)
La función WNetAddConnection3 establece una conexión a un recurso de red. La función puede redirigir un dispositivo local al recurso de red.
La función WNetAddConnection3 es similar a la función WNetAddConnection2 . La principal diferencia es que WNetAddConnection3 tiene un parámetro adicional, un identificador para una ventana que el proveedor de recursos de red puede usar como ventana de propietario para los cuadros de diálogo. La función WNetAddConnection2 y la función WNetAddConnection3 sustituyen a la función WNetAddConnection .
Sintaxis
DWORD WNetAddConnection3A(
[in] HWND hwndOwner,
[in] LPNETRESOURCEA lpNetResource,
[in] LPCSTR lpPassword,
[in] LPCSTR lpUserName,
[in] DWORD dwFlags
);
Parámetros
[in] hwndOwner
Identificador de una ventana que el proveedor de recursos de red puede usar como ventana de propietario para los cuadros de diálogo. Use este parámetro si establece el valor de CONNECT_INTERACTIVE en el parámetro dwFlags .
El parámetro hwndOwner puede ser NULL. Si es así, una llamada a WNetAddConnection3 equivale a llamar a la función WNetAddConnection2 .
[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 .
La función WNetAddConnection3 omite los demás miembros de la estructura NETRESOURCE .
[in] lpPassword
Puntero a una cadena terminada en null que especifica una contraseña que se 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 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. Actualmente se definen los siguientes valores.
| Valor | Significado |
|---|---|
|
Si se establece esta marca, el sistema operativo puede interactuar con el usuario con fines de autenticación. |
|
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. |
|
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:. |
|
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 cuando apunta a una cadena vacía). Si esta marca de bits está desactivada, el sistema operativo no restaura automáticamente la conexión en el inicio de sesión. |
|
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 2000/NT y Windows Me/98/95: Este valor no se admite. |
|
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 también se omite a menos que establezca la marca de CONNECT_COMMANDLINE.
Windows 2000/NT y Windows Me/98/95: Este valor no se admite. |
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 |
|---|---|
|
El autor de la llamada no tiene acceso al recurso de red. |
|
El dispositivo local especificado por el miembro lpLocalName ya está conectado a un recurso de red. |
|
El tipo de dispositivo local y el tipo de recurso de red no coinciden. |
|
El valor especificado por lpLocalName no es válido. |
|
El valor especificado por el miembro lpRemoteName no es aceptable para ningún proveedor de recursos de red, ya sea porque el nombre del recurso no es válido o porque no se encuentra el recurso con nombre. |
|
El perfil de usuario tiene un formato incorrecto. |
|
El valor especificado por el miembro lpProvider no coincide con ningún proveedor. |
|
El enrutador o proveedor está ocupado, posiblemente inicializando. El autor de la llamada debe reintentar. |
|
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. |
|
El sistema no puede abrir el perfil de usuario para procesar conexiones persistentes. |
|
Una entrada para el dispositivo especificado por el miembro lpLocalName ya está en el perfil de usuario. |
|
Error específico de la red. Llame a la función WNetGetLastError para obtener una descripción del error. |
|
La contraseña especificada no es válida y no se establece la marca CONNECT_INTERACTIVE. |
|
No se puede realizar la operación porque no se inicia un componente de red o porque no se puede usar un nombre especificado. |
|
La red no está disponible. |
Comentarios
La función WNetUseConnection es similar a la función WNetAddConnection3 . La principal diferencia es que WNetUseConnection puede seleccionar automáticamente un dispositivo local sin usar para redirigir al recurso de red.
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 WNetAddConnection3 , 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 WNetAddConnection3 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.
Nota
El encabezado winnetwk.h define WNetAddConnection3 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 | winnetwk.h |
| Library | Mpr.lib |
| Archivo DLL | Mpr.dll |