WNetAddConnection2
La función WNetAddConnection2 crea una conexión a un recurso de red y puede redirigir un dispositivo local a un recurso de red.
La función WNetAddConnection2 sustituye a la función WNetAddConnection. Si se puede pasar un manipulador de una ventana que el proveedor de recursos de red pueda usar como una ventana propietaria para cuadros de diálogo, invocar la función WNetAddConnection3 en su lugar.
Sintaxis
DWORD WNetAddConnection2( LPNETRESOURCE lpNetResource, LPCTSTR lpPassword, LPCTSTR lpUsername, DWORD dwFlags );
Parámetros
- lpNetResource
- Un puntero a una estructura NETRESOURCE que especifica detalles de la conexión propuesta, como información sobre el
recurso de red, el dispositivo local y el proveedor de recurso de red.
Se deben especificar los siguientes miembros de la estructura NETRESOURCE.
Miembro Significado dwType El tipo de recurso de red al que conectarse.
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 sea requerido, su información puede ser ignorada por el proveedor del servicio de red.lpLocalName Un puntero a una cadena termianda en cero que especifica el nombre de un dispositivo local a redirigir, como "F:" o "LPT1". La cadena se trata de forma case-insensitive.
Si la cadena está vacía o si lpLocalName es NULL, la función crea una conexión al recurso de red sin redirigirla a un dispositivo local.lpRemoteName Un puntero a una cadena terminada en cero que especifica el recurso de red al que conectarse. La cadena puede tener hasta MAX_PATH caracteres de longitud, y debe serguir las convenciones de nombres del proveerdor de red. lpProvider Un puntero a una cadena terminada en cero 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 pasando la cadena apuntada por el miembro lpRemoteName.
Si este miembro no es NULL, el sistema operativo intenta hacer una conexión sólo con el proveedor de red indicado.
Se debe asignar este miembro sólo si se conoce el proveedor de red que se quiere usar. En caso contrario, dejar al sistema operativo determinar qué nombre de proveedor de red mapear. - lpPassword
- Un puntero a una cadena constante termianda en cero que especifica la contraseña a usar en la conexión de red.
Si lpPassword es NULL, la función usa la contraseña por defecto asociada con el usuario especificado por el parámetro lpUserName.
Si lpPassword apunta a una cadena vacía, la función no usa contraseña.
Si la conexión falla debido a una contraseña inválida y el valor CONNECT_INTERACTIVE está asignado en el parámetro dwFlags, la función muestra un cuadro de diálogo para que el usuario introduzca la contraseña.
Windows Me/98/95: Este parámetro debe ser NULL o una cadena vacía. - lpUsername
- Un puntero a una cadena constante terminada en nulo que especifica un nombre de usuario para hacer la conexión.
Si lpUserName es NULL, la función usa el nombre de usuario por defecto. (El contexto de usuario para el proceso proporciona el nombre de usuario por defecto.)
El parámetro lpUserName se especifica cuando los usuarios quieren conectarse a un recurso de red para el que se ha asignado un nombre de usuario o cuenta distinto del nombre de usuario o cuenta por defecto.
La cadena de nombre de usuario representa un contexto de seguridad. Debe ser específica para un proveedor de red.
Windows Me/98/95: Este parámetro debe ser NULL o una cadena vacía. - dwFlags
- Un conjunto de opciones de conexión. Los posibles valores para las opciones de conexión están definidas en el fichero de cabecera
Winnetwk.h. Actualmente se pueden usar los siguientes valores.
Valor Significado CONNECT_UPDATE_PROFILE
0x00000001The network resource connection should be remembered. If this bit flag is set, the operating system automatically attempts to restore the connection when the user logs on. The operating system remembers only successful connections that redirect local devices. It does not remember connections that are unsuccessful or deviceless connections. (A deviceless connection occurs when the lpLocalName member is NULL or points to an empty string.) If this bit flag is clear, the operating system does not try to restore the connection when the user logs on. CONNECT_UPDATE_RECENT
0x00000002The network resource connection should not be put in the recent connection list. If this flag is set and the connection is successfully added, the network resource connection will be put in the recent connection list only if it has a redirected local device associated with it.
Valor de retorno
Si la función tiene éxito, the return value is NO_ERROR.
If the function fails, the return value can be one of the following error codes or one of the system error codes.
Observaciones
On Windows Server 2003 and Windows XP, the WNet functions create and delete network drive letters in the MS-DOS device namespace associated with a logon session because MS-DOS devices are identified by AuthenticationID (a locally unique identifier, or LUID, associated with a logon session.) This can affect applications that call one of the WNet functions to create a network drive letter under one user logon, but query for existing network drive letters under a different user logon. An example of this situation could be when a user's second logon is created within a logon session, for example, by calling the CreateProcessAsUser function, and the second logon runs an application that calls the GetLogicalDrives function. The call to the GetLogicalDrives function does not return network drive letters created by WNet function calls under the first logon. Note that in the preceding example the first logon session still exists, and the example could apply to any logon session, including a Terminal Services session. For more information, see Defining an MS-DOS Device Name. On Windows Server 2003 and Windows XP, if a service that runs as LocalSystem calls the WNetAddConnection2 function, then the mapped drive is visible to all user logon sessions. For Microsoft network providers, the lpRemoteName member of the NETRESOURCE structure pointed to by the lpNetResource parameter can contain an IPv4 address in dotted-decimal notation. An example for a share might be the following: \\192.168.1.1\share For Microsoft network providers on Windows Vista and later, the lpRemoteName member of the NETRESOURCE structure pointed to by the lpNetResource parameter can contain an IPv6 address. However, the IPv6 literal format must be used so that the IPv6 address is parsed correctly. An IPv6 literal address is of the form: ipv6-address with the ':' characters replaced by '-' characters followed by the ".ipv6-literal.net" string. For example, for the following IPv6 address: 2001:4898:9:3:c069:aa97:fe76:2449 an example for a share might be the following: \\2001-4898-9-3-c069-aa97-fe76-2449.ipv6-literal.net\share Other network providers may support the lpRemoteName member of the NETRESOURCE structure pointed to by the lpNetResource parameter that contains an IPv4 or IPv6 address, but this is up to specific network provider. Windows 7 and Windows Server 2008 R2: If the WNetAddConnection2 function is called with explicit user credentials specified in the pUsername and lpPassword to establish a connection with a network resource on a specific server and then called again with either of these parameters as NULL (to use the default user name or default password) to the same server, the call with fail. The error returned will be ERROR_BAD_USERNAME or ERROR_INVALID_PASSWORD.