Función WNetUseConnectionA (winnetwk.h)

Artículo
11/20/2024

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

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.

Sintaxis

DWORD WNetUseConnectionA(
  [in]      HWND           hwndOwner,
  [in]      LPNETRESOURCEA lpNetResource,
  [in]      LPCSTR         lpPassword,
  [in]      LPCSTR         lpUserId,
  [in]      DWORD          dwFlags,
  [out]     LPSTR          lpAccessName,
  [in, out] LPDWORD        lpBufferSize,
  [out]     LPDWORD        lpResult
);

Parámetros

[in] hwndOwner

Controlar en 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 de .

[in] lpNetResource

Puntero a una estructura de NETRESOURCE que especifica los detalles de la conexión propuesta. La estructura contiene 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 de NETRESOURCE.

Miembro	Significado
dwType	Especifica el tipo de recurso al que conectarse. Es más eficaz especificar un tipo de recurso en este miembro, como RESOURCETYPE_DISK o RESOURCETYPE_PRINT. Sin embargo, si el miembro de lpLocalName es NULL, o si apunta a una cadena vacía y no se establece CONNECT_REDIRECT, dwType puede ser RESOURCETYPE_ANY. Este método solo funciona si la función no elige automáticamente un dispositivo para redirigir al recurso de red. Aunque este miembro es necesario, el proveedor de servicios de red puede omitir su información.
lpLocalName	Puntero a un cadena terminada en nullque 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, se produce una conexión a la red sin redireccionamiento. Si el valor de CONNECT_REDIRECT se establece en el parámetro dwFlags, o si la red requiere un dispositivo local redirigido, la función elige un dispositivo local para redirigir y devuelve el nombre del dispositivo en el parámetro lpAccessName.
lpRemoteName	Puntero a un cadena terminada en nullque 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 un cadena terminada en nullque 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. Debe establecer este miembro solo 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 WNetUseConnection omite los demás miembros de la estructura de NETRESOURCE. Para obtener más información, consulte las descripciones siguientes para el parámetro dwFlags.

[in] lpPassword

Puntero a una constante cadena terminada en nullque 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 lpUserID.

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.

[in] lpUserId

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

Si lpUserID 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 lpUserID 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.

[in] dwFlags

Conjunto de marcas de bits que describen la conexión. Este parámetro puede ser cualquier combinación de los valores siguientes.

Valor	Significado
CONNECT_INTERACTIVE	Si se establece esta marca, el sistema operativo puede interactuar con el usuario con fines de autenticación.
CONNECT_PROMPT	Esta marca indica al sistema que no use ninguna configuración predeterminada para los 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	Esta marca fuerza la redirección de un dispositivo local al realizar la conexión. Si el lpLocalName miembro 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 XP: Cuando el sistema asigna automáticamente letras de unidad de red, las letras se asignan a partir de Z:, después Y:, y finalizan con C:. Esto reduce la colisión entre letras de unidad de inicio de sesión (como letras de unidad de red) y letras de unidad global (como unidades de disco). Tenga en cuenta que las versiones anteriores asignan letras de unidad a partir de C: y que terminan con Z:.
CONNECT_UPDATE_PROFILE	Esta marca indica al sistema operativo que almacene 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 recuerda solo las conexiones correctas que redirigen los dispositivos locales. No recuerda las conexiones incorrectas o sin dispositivo. (Una conexión sin dispositivo se produce cuando 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.
CONNECT_COMMANDLINE	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.
CONNECT_CMD_SAVECRED	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 CONNECT_COMMANDLINE. Windows 2000/NT y Windows Me/98/95: Este valor no se admite.

[out] lpAccessName

Puntero a un búfer que recibe solicitudes del sistema en la conexión. Este parámetro puede ser null.

Si se especifica este parámetro y el lpLocalName miembro de la estructura NETRESOURCE especifica un dispositivo local, este búfer recibe el nombre del dispositivo local. Si lpLocalName no especifica un dispositivo y la red requiere una redirección de dispositivos local, o si se establece el valor de CONNECT_REDIRECT, este búfer recibe el nombre del dispositivo local redirigido.

De lo contrario, el nombre copiado en el búfer es el de un recurso remoto. Si se especifica, este búfer debe ser al menos tan grande como la cadena a la que apunta el miembro lpRemoteName.

[in, out] lpBufferSize

Puntero a una variable que especifica el tamaño del lpAccessName búfer, en caracteres. Si se produce un error en la llamada porque el búfer no es lo suficientemente grande, la función devuelve el tamaño de búfer necesario en esta ubicación. Para obtener más información, vea las descripciones del parámetro lpAccessName y el código de error ERROR_MORE_DATA en la sección Valores devueltos.

[out] lpResult

Puntero a una variable que recibe información adicional sobre la conexión. Este parámetro puede ser el siguiente valor.

Valor	Significado
CONNECT_LOCALDRIVE	Si se establece esta marca, la conexión se realizó mediante una redirección de dispositivos local. Si el parámetro lpAccessName apunta a un búfer, el nombre del dispositivo local se copia en el búfer.

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_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_DEVICE	El valor especificado por lpLocalName no es válido.
ERROR_BAD_NET_NAME	El valor especificado por el lpRemoteName miembro no es aceptable para ningún proveedor de recursos de red porque el nombre del recurso no es válido o porque el recurso con nombre no se puede encontrar.
ERROR_BAD_PROVIDER	El valor especificado por el miembro lpProvider no coincide con ningún proveedor.
ERROR_CANCELLED	El intento de realizar la conexión fue cancelada por el usuario a través de un cuadro de diálogo de uno de los proveedores de recursos de red o por un recurso llamado.
ERROR_EXTENDED_ERROR	Error específico de la red. Para obtener una descripción del error, llame a la función WNetGetLastError.
ERROR_INVALID_ADDRESS	El autor de la llamada pasó un puntero a un búfer al que no se pudo tener acceso.
ERROR_INVALID_PARAMETER	Este error es el resultado de una de las condiciones siguientes: El miembro lpRemoteName de NULL. Además, lpAccessName no es NULL, pero lpBufferSize es NULL o apunta a cero. El miembro dwType no es RESOURCETYPE_DISK ni RESOURCETYPE_PRINT. Además, CONNECT_REDIRECT se establece en dwFlags y lpLocalName es NULLo la conexión es a una red que requiere la redirección de un dispositivo local.
ERROR_INVALID_PASSWORD	La contraseña especificada no es válida y no se establece la marca CONNECT_INTERACTIVE.
ERROR_MORE_DATA	El búfer de lpAccessName es demasiado pequeño. Si se redirige un dispositivo local, el búfer debe ser lo suficientemente grande como para contener el nombre del dispositivo local. De lo contrario, el búfer debe ser lo suficientemente grande como para contener la cadena a la que apunta lpRemoteNameo el nombre del recurso conectable cuyo alias apunta lpRemoteName. Si se devuelve este error, no se ha realizado ninguna conexión.
ERROR_NO_MORE_ITEMS	El sistema operativo no puede elegir automáticamente una redirección local porque todos los dispositivos locales válidos están en uso.
ERROR_NO_NET_OR_BAD_PATH	No se pudo completar la operación, ya sea porque no se ha iniciado un componente de red o porque no se reconoce el nombre del recurso especificado.
ERROR_NO_NETWORK	La red no está disponible.

Observaciones

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

Nota

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