Función WNetGetUniversalNameA (winnetwk.h)
La función WNetGetUniversalName toma una ruta de acceso basada en unidades para un recurso de red y devuelve una estructura de información que contiene una forma más universal del nombre.
Sintaxis
DWORD WNetGetUniversalNameA(
[in] LPCSTR lpLocalPath,
[in] DWORD dwInfoLevel,
[out] LPVOID lpBuffer,
[in, out] LPDWORD lpBufferSize
);
Parámetros
[in] lpLocalPath
Puntero a una cadena terminada en null constante que es una ruta de acceso basada en unidades para un recurso de red.
Por ejemplo, si la unidad H se ha asignado a un recurso compartido de unidad de red y el recurso de red de interés es un archivo denominado Sample.doc en el directorio \Win32\Examples en ese recurso compartido, la ruta de acceso basada en unidades se H:\Win32\Examples\Sample.doc.
[in] dwInfoLevel
Tipo de estructura a la que almacena la función en el búfer al que apunta el parámetro lpBuffer . Este parámetro puede ser uno de los siguientes valores definidos en el archivo de encabezado Winnetwk.h .
| Valor | Significado |
|---|---|
|
La función almacena una estructura de UNIVERSAL_NAME_INFO en el búfer. |
|
La función almacena una estructura REMOTE_NAME_INFO en el búfer. |
La estructura de UNIVERSAL_NAME_INFO apunta a una cadena de nombre de convención de nomenclatura universal (UNC).
La estructura REMOTE_NAME_INFO apunta a una cadena de nombre UNC y dos cadenas de información de conexión adicionales. Para obtener más información, vea la sección Comentarios que se muestra más adelante.
[out] lpBuffer
Puntero a un búfer que recibe la estructura especificada por el parámetro dwInfoLevel .
[in, out] lpBufferSize
Puntero a una variable que especifica el tamaño, en bytes, del búfer al que apunta el parámetro lpBuffer .
Si la función se ejecuta correctamente, establece la variable a la que apunta lpBufferSize en el número de bytes almacenados en el búfer. Si se produce un error en la función porque el búfer es demasiado pequeño, esta ubicación recibe el tamaño de búfer necesario y la función devuelve ERROR_MORE_DATA.
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 |
|---|---|
|
La cadena a la que apunta el parámetro lpLocalPath no es válida. |
|
No hay ninguna conexión actual con el dispositivo remoto, pero hay una conexión recordada (persistente) con él. |
|
Error específico de la red. Use la función WNetGetLastError para obtener una descripción del error. |
|
El búfer al que apunta el parámetro lpBuffer es demasiado pequeño. La función establece la variable a la que apunta el parámetro lpBufferSize al tamaño de búfer necesario. Hay más entradas disponibles con llamadas posteriores. |
|
El parámetro dwInfoLevel se establece en UNIVERSAL_NAME_INFO_LEVEL, pero el proveedor de red no admite nombres UNC. (Ninguno de los proveedores de red admite esta función). |
|
Ninguno de los proveedores de red reconoce el nombre local como tener una conexión. Sin embargo, la red no está disponible para al menos un proveedor al que puede pertenecer la conexión. |
|
La red no está disponible. |
|
El dispositivo especificado por el parámetro lpLocalPath no se redirige. |
Comentarios
Una forma universal de una ruta de acceso basada en unidad local identifica un recurso de red de forma inequívoca e independiente del equipo. A continuación, el nombre se puede pasar a los procesos de otros equipos, lo que permite que esos procesos obtengan acceso al recurso.
La función WNetGetUniversalName admite actualmente un formato de nombre universal: nombres de convención de nomenclatura universal (UNC), que parecen los siguientes:
\\servername\sharename\path\file
Con el ejemplo de la descripción anterior del parámetro lpLocalPath , si la unidad de red compartida está en un servidor denominado COOLSERVER y el nombre del recurso compartido es HOTSHARE, el nombre UNC del recurso de red cuyo nombre basado en unidad se H:\Win32\Examples\Sample.doc sería el siguiente:
\\coolserver\hotshare\win32\examples\sample.doc
La estructura UNIVERSAL_NAME_INFO contiene un puntero a una cadena de nombre UNC. La estructura REMOTE_NAME_INFO también contiene un puntero a una cadena de nombre UNC, así como punteros a otras dos cadenas útiles. Por ejemplo, un proceso puede pasar el miembro lpszConnectionInfo de la estructura REMOTE_NAME_INFO a la función WNetAddConnection2 para conectar un dispositivo local al recurso de red. A continuación, el proceso puede anexar la cadena a la que apunta el miembro lpszRemainingPath a la cadena del dispositivo local. La cadena resultante se puede pasar a funciones que requieren una ruta de acceso basada en unidades.
El parámetro lpLocalPath no tiene que especificar una ruta de acceso o recurso que ya esté presente en un recurso remoto. Por ejemplo, el parámetro lpLocalPath podría especificar y carpeta, una jerarquía de carpetas o un archivo que no existe actualmente. La función WNetGetUniversalName devuelve una forma más universal del nombre en estos casos.
El tamaño del búfer al que apunta el parámetro lpBuffer y especificado en el parámetro lpBufferSize debe ser mucho mayor que el tamaño de las estructuras de REMOTE_NAME_INFO o UNIVERSAL_NAME_INFO . El búfer al que apunta el parámetro lpBuffer debe ser lo suficientemente grande como para almacenar las cadenas UNC a las que apuntan los miembros de las estructuras REMOTE_NAME_INFO o UNIVERSAL_NAME_INFO . Si el tamaño del búfer es demasiado pequeño, la función produce un error con ERROR_MORE_DATA y la variable a la que apunta el parámetro lpBufferSize indica el tamaño de búfer necesario.
Windows Server 2003 y Windows XP: Esta función consulta los espacios de nombres de dispositivo MS-DOS asociados a una sesión de inicio de sesión porque los dispositivos MS-DOS se identifican mediante AuthenticationID. (Un AuthenticationID es el 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 . GetLogicalDrives no devuelve letras de unidad de red creadas por una función 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.
Ejemplos
En el ejemplo de código siguiente se muestra cómo usar la función WNetGetUniversalName para recuperar las cadenas de nombre UNC universal asociadas a la ruta de acceso basada en unidades para 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>
int wmain(int argc, wchar_t * argv[])
{
DWORD dwRetVal;
WCHAR Buffer[1024];
DWORD dwBufferLength = 1024;
UNIVERSAL_NAME_INFO * unameinfo;
REMOTE_NAME_INFO *remotenameinfo;
wprintf(L"Calling WNetGetUniversalName with Local Path = %s\n", argv[1]);
unameinfo = (UNIVERSAL_NAME_INFO *) &Buffer;
dwRetVal = WNetGetUniversalName(argv[1], UNIVERSAL_NAME_INFO_LEVEL, (LPVOID) unameinfo, &dwBufferLength );
//
// If the call succeeds, print the user information.
//
if (dwRetVal == NO_ERROR) {
wprintf(L"WNetGetUniversalName returned success for InfoLevel=UNIVERSAL_NAME_INFO_LEVEL\n");
wprintf(L"\tUniversal name = %s\n", unameinfo->lpUniversalName);
}
else {
wprintf(L"WNetGetUser failed for InfoLevel=UNIVERSAL_NAME_INFO_LEVEL with error: %u\n", dwRetVal);
}
remotenameinfo = (REMOTE_NAME_INFO *) &Buffer;
dwRetVal = WNetGetUniversalName(argv[1], REMOTE_NAME_INFO_LEVEL,
(LPVOID) remotenameinfo, &dwBufferLength );
//
// If the call succeeds, print the user information.
//
if (dwRetVal == NO_ERROR) {
wprintf(L"WNetGetUniversalName returned success for InfoLevel=REMOTE_NAME_INFO_LEVEL\n");
wprintf(L"\tUniversal name = %s\n", remotenameinfo->lpUniversalName);
wprintf(L"\tConnection name = %s\n", remotenameinfo->lpConnectionName);
wprintf(L"\tRemaining path = %s\n", remotenameinfo->lpRemainingPath);
}
else {
wprintf(L"WNetGetUser failed for InfoLevel=REMOTE_NAME_INFO_LEVEL with error: %u\n", dwRetVal);
}
}
Nota
El encabezado winnetwk.h define WNetGetUniversalName 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 |
Consulte también
Determinar la ubicación de un recurso compartido