Función WNetGetUniversalNameA (winnetwk.h)

Artículo
11/20/2024

La función WNetGetUniversalName toma una ruta de acceso basada en unidad 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 unidad 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
UNIVERSAL_NAME_INFO_LEVEL	La función almacena una estructura UNIVERSAL_NAME_INFO en el búfer.
REMOTE_NAME_INFO_LEVEL	La función almacena una estructura REMOTE_NAME_INFO en el búfer.

La estructura 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 siguiente sección Comentarios.

[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 realiza correctamente, establece la variable a la que apunta lpBufferSize al 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 valores siguientes.

Código devuelto	Descripción
ERROR_BAD_DEVICE	La cadena a la que apunta el parámetro lpLocalPath no es válida.
ERROR_CONNECTION_UNAVAIL	No hay ninguna conexión actual con el dispositivo remoto, pero hay una conexión recordada (persistente) con él.
ERROR_EXTENDED_ERROR	Error específico de la red. Use la función WNetGetLastError para obtener una descripción del error.
ERROR_MORE_DATA	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 en el tamaño de búfer necesario. Hay más entradas disponibles con llamadas posteriores.
ERROR_NOT_SUPPORTED	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).
ERROR_NO_NET_OR_BAD_PATH	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.
ERROR_NO_NETWORK	La red no está disponible.
ERROR_NOT_CONNECTED	El dispositivo especificado por el parámetro lpLocalPath no se redirige.

Observaciones

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 tienen un aspecto similar al siguiente:

\\servername\sharename\path\file

Con el ejemplo de la descripción anterior de la 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 es 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 de 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 de 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 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 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.

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