Función NetDfsEnum (lmdfs.h)
Enumera los espacios de nombres del Sistema de archivos distribuidos (DFS) hospedados en un servidor o vínculos DFS de un espacio de nombres hospedado por un servidor.
Sintaxis
NET_API_STATUS NET_API_FUNCTION NetDfsEnum(
[in] LPWSTR DfsName,
[in] DWORD Level,
[in] DWORD PrefMaxLen,
[out] LPBYTE *Buffer,
[out] LPDWORD EntriesRead,
[in, out] LPDWORD ResumeHandle
);
Parámetros
[in] DfsName
Puntero a una cadena que especifica la ruta de acceso de convención de nomenclatura universal (UNC) de la raíz o vínculo DFS.
Al especificar el nivel de información 200 (DFS_INFO_200), este parámetro es el nombre de un dominio. Al especificar el nivel de información 300 (DFS_INFO_300), este parámetro es el nombre de un servidor.
Para todos los demás niveles, la cadena puede estar en una de las cuatro formas siguientes:
Nombredeservidor\DfsName
o
Nombredeservidor\DfsName\link_path
donde ServerName es el nombre del servidor de destino raíz que hospeda el espacio de nombres DFS independiente; Dfsname es el nombre del espacio de nombres DFS; y link_path es un vínculo DFS.
La cadena también puede tener los siguientes formatos:
Nombrededominio\DomainName\DomDfsName
o
Nombrededominio\DomDfsName\link_path
donde DomainName es el nombre del dominio que hospeda la raíz DFS basada en dominio; DomDfsName es el nombre del espacio de nombres DFS; y link_path es un vínculo DFS.
Puede preceder a la cadena con barras diagonales inversas (\), pero no son necesarias. Este parámetro es obligatorio.
[in] Level
Especifica el nivel de información de la solicitud. Este parámetro puede ser uno de los valores siguientes.
1
Devuelve el nombre de la raíz DFS y todos los vínculos debajo de la raíz. El parámetro Buffer apunta a una matriz de estructuras de DFS_INFO_1 .
2
Devuelve el nombre, el comentario, el estado y el número de destinos para la raíz DFS y todos los vínculos bajo la raíz. El parámetro Buffer apunta a una matriz de estructuras de DFS_INFO_2 .
3
Devuelve el nombre, el comentario, el estado, el número de destinos y la información sobre cada destino para la raíz DFS y todos los vínculos debajo de la raíz. El parámetro Buffer apunta a una matriz de estructuras de DFS_INFO_3 .
4
Devuelve el nombre, comentario, estado, GUID, tiempo de espera, número de destinos e información sobre cada destino para la raíz DFS y todos los vínculos bajo la raíz. El parámetro Buffer apunta a una matriz de estructuras de DFS_INFO_4 .
5
Devuelve el nombre, el estado, el GUID, el tiempo de espera, las marcas de propiedad, el tamaño de los metadatos y el número de destinos de una raíz DFS y todos los vínculos de la raíz. El parámetro Buffer apunta a una matriz de estructuras de DFS_INFO_5 .
6
Devuelve el nombre, el estado, el GUID, el tiempo de espera, las marcas de propiedad, el tamaño de los metadatos, la información de destino DFS para una raíz o vínculo y una lista de destinos DFS. El parámetro Buffer apunta a una matriz de estructuras DFS_INFO_6 .
8
Devuelve el nombre, el estado, el GUID, el tiempo de espera, las marcas de propiedad, el tamaño de los metadatos, el número de destinos y los descriptores de seguridad de punto de reanálisis de vínculos para una raíz DFS y todos los vínculos debajo de la raíz. El parámetro Buffer apunta a una matriz de estructuras de DFS_INFO_8 .
9
Devuelve el nombre, el estado, el GUID, el tiempo de espera, las marcas de propiedad, el tamaño de los metadatos, la información de destino DFS, los descriptores de seguridad de punto de análisis de vínculos y una lista de destinos DFS para una raíz o vínculo. El parámetro Buffer apunta a una matriz de estructuras de DFS_INFO_9 .
200
Devuelve la lista de espacios de nombres DFS basados en dominio en el dominio. El parámetro Buffer apunta a una matriz de estructuras de DFS_INFO_200 .
300
Devuelve los espacios de nombres DFS independientes y basados en dominio hospedados por un servidor. El parámetro Buffer apunta a una matriz de estructuras de DFS_INFO_300 .
[in] PrefMaxLen
Especifica el número de bytes que debe devolver esta función en el búfer de estructura de información. Si este parámetro es MAX_PREFERRED_LENGTH, la función asigna la cantidad de memoria necesaria para los datos. Para obtener más información, vea la sección Comentarios que se muestra más adelante. Este parámetro se omite si especifica el nivel 200 o el nivel 300.
[out] Buffer
Puntero a un búfer que recibe las estructuras de información solicitadas. El formato de estos datos depende del valor del parámetro Level . El sistema asigna este búfer y se debe liberar mediante la función NetApiBufferFree .
[out] EntriesRead
Puntero a un valor que recibe el número real de entradas devueltas en la respuesta.
[in, out] ResumeHandle
Puntero a un valor que contiene un identificador que se va a usar para continuar una enumeración cuando hay más datos disponibles de los que se pueden devolver en una sola llamada a esta función. El identificador debe ser cero en la primera llamada y dejar sin cambios para las llamadas posteriores. Para obtener más información, vea la sección Comentarios que se muestra más adelante.
Valor devuelto
Si la función se ejecuta correctamente, el valor devuelto es NERR_Success.
Si no hay más entradas disponibles para enumerarse, el valor devuelto se ERROR_NO_MORE_ITEMS.
Si se produce un error en la función, el valor devuelto es un código de error del sistema. Para obtener una lista de códigos de error, consulte Códigos de error del sistema.
Comentarios
No se requiere ninguna pertenencia especial a grupos para usar la función NetDfsEnum .
Llame a la función NetDfsEnum con el parámetro ResumeHandle establecido en cero para comenzar la enumeración. Para continuar con la operación de enumeración, llame a esta función con resumeHandle devuelto por la llamada anterior a NetDfsEnum. Si esta función no devuelve ERROR_NO_MORE_ITEMS, las llamadas posteriores a esta API devolverán los vínculos restantes. Una vez que se devuelve ERROR_NO_MORE_ITEMS , se han recuperado todos los vínculos DFS disponibles.
La función NetDfsEnum asigna la memoria necesaria para el búfer de estructura de información. Si especifica una cantidad en el parámetro PrefMaxLen , restringe la memoria que devuelve la función. Sin embargo, el tamaño real de la memoria que asigna la función NetDfsEnum puede ser mayor que la cantidad especificada. Para obtener más información, consulte Longitudes de búfer de funciones de administración de red.
Debido a la posibilidad de actualizaciones simultáneas en el espacio de nombres DFS, el autor de la llamada no debe asumir integridad ni unicidad de los resultados devueltos al reanudar una operación de enumeración.
Ejemplos
En el ejemplo de código siguiente se muestra cómo enumerar los vínculos DFS en una raíz DFS con nombre con una llamada a la función NetDfsEnum . El ejemplo llama a NetDfsEnum, especificando el nivel de información 3 ( DFS_INFO_3). El código de ejemplo recorre en bucle las entradas e imprime los datos recuperados y el estado de cada servidor host al que hace referencia el vínculo DFS. Por último, el ejemplo libera la memoria asignada para el búfer de información.
#include <windows.h>
#include <lm.h>
#include <lmdfs.h>
#include <stdio.h>
#pragma comment(lib, "Netapi32.lib")
void wmain(int argc, wchar_t *argv[ ])
{
PDFS_INFO_3 pData, p;
PDFS_STORAGE_INFO ps;
DWORD er = 0, hResume = 0, res, i, j;
if(argc < 2)
wprintf(L"Syntax: %s \\\\DfsName\n", argv[0]);
else
{
//
// Call the NetDfsEnum function, specifying level 3.
//
res = NetDfsEnum(argv[1], 3, MAX_PREFERRED_LENGTH, (LPBYTE *) &pData, &er, &hResume);
// Call NetDfsEnum until all available entries are returned.
// NetDfsEnum will return ERROR_NO_MORE_ITEMS when all entries
// have been obtained.
while (res == ERROR_SUCCESS)
{
p = pData;
//
// Loop through the entries; print the data.
//
for(i = 1; i <= er; i++)
{
printf("%-30S%u\n", p->EntryPath, p->NumberOfStorages);
ps = p->Storage;
//
// Loop through each target.
//
for(j = 1; j <= p->NumberOfStorages; j++)
{
//
// Print the status (Offline/Online) and the name
// of each target referenced by the DFS link.
//
printf(" %S ", (ps->State == DFS_STORAGE_STATE_OFFLINE) ? TEXT("Offline"):TEXT("Online "));
printf("\\\\%S\\%S\n", ps->ServerName, ps->ShareName);
ps++;
}
p++;
}
// Free the allocated buffer.
//
NetApiBufferFree(pData);
res = NetDfsEnum(argv[1], 3, MAX_PREFERRED_LENGTH, (LPBYTE *) &pData, &er, &hResume);
}
if (res == ERROR_NO_MORE_ITEMS)
{
// the last of the entries have been processed.
res = ERROR_SUCCESS;
printf("Enumeration done\n");
}
else
{
// an error occurred.
printf("Error: %u\n", res);
}
}
return;
}
Requisitos
| Cliente mínimo compatible | Windows Vista |
| Servidor mínimo compatible | Windows Server 2008 |
| Plataforma de destino | Windows |
| Encabezado | lmdfs.h (include LmDfs.h, Lm.h) |
| Library | Netapi32.lib |
| Archivo DLL | Netapi32.dll |
Consulte también
Funciones del sistema de archivos distribuidos (DFS)