Share via

3.1.4.1 NetrConnectionEnum (Opnum 8)

  • Article

The NetrConnectionEnum method lists all the treeconnects made to a shared resource on the server or all treeconnects established from a particular computer.

 NET_API_STATUS NetrConnectionEnum(
   [in, string, unique] SRVSVC_HANDLE ServerName,
   [in, string, unique] WCHAR* Qualifier,
   [in, out] LPCONNECT_ENUM_STRUCT InfoStruct,
   [in] DWORD PreferedMaximumLength,
   [out] DWORD* TotalEntries,
   [in, out, unique] DWORD* ResumeHandle
 );

ServerName: An SRVSVC_HANDLE (section 2.2.1.1) pointer that identifies the server. The client MUST map this structure to an RPC binding handle (see [C706] sections 4.3.5 and 5.1.5.2). The server MUST ignore this parameter.

Qualifier: A pointer to a null-terminated UTF-16 string that specifies a share name or computer name for the connections of interest to the client.

InfoStruct: A pointer to a structure, in the format of a CONNECT_ENUM_STRUCT (section 2.2.4.5). The CONNECT_ENUM_STRUCT structure has a Level member that specifies the type of structure to return. The Level member MUST be one of the values specified in section 2.2.4.5.

PreferedMaximumLength: Specifies the preferred maximum length, in bytes, of the returned data. If the value that is specified is MAX_PREFERRED_LENGTH (section 2.2.2.2), the method MUST attempt to return all entries.

TotalEntries: The total number of entries that could have been enumerated if the buffer had been big enough to hold all the entries.

ResumeHandle: A pointer to a value that contains a handle that is used to continue an existing TreeConnect search. The handle MUST be zero on the first call and left unchanged for subsequent calls. If ResumeHandle is NULL, a resume handle MUST NOT be stored. If this parameter is not NULL and the method returns ERROR_MORE_DATA, this parameter receives an implementation-specific nonzero value that can be passed in subsequent calls to this method to continue with the enumeration.

If this parameter is NULL or points to 0x00000000, the enumeration starts from the beginning of the TreeConnectList.

Return Values: The method returns 0x00000000 (NERR_Success) to indicate success; otherwise, it returns a nonzero error code. The method can take any specific error code value, as specified in [MS-ERREF] section 2.2.

In response to a NetrConnectionEnum request, the server MUST enumerate the tree connection entries in TreeConnectList based on the value of the ResumeHandle parameter. For each entry, the server MUST query treeconnect properties by invoking underlying server events as specified in [MS-CIFS] section 3.3.4.15 and [MS-SMB2] section 3.3.4.19, providing TreeConnect.GlobalTreeConnectId as the input parameter. When the server receives STATUS SUCCESS for a treeConnect.GlobalTreeConnectId from either a CIFS or SMB2 server, the server MUST consider the received CONNECTION_INFO_1 structure as valid, and it MUST continue to query all other treeconnects that are established on the server.

The server MUST filter the results of the queries based on the Qualifier input parameter:

The Qualifier parameter specifies a share name or computer name for treeconnects of interest to the client. If the Qualifier begins with "\\", it is considered a computer name. Otherwise, it is considered a share name. Share names MUST NOT begin with "\\".

If the Qualifier is the name of a share on the server, the server MUST return all treeconnects made to that share by returning only the entries where treeconnect. coni1_netname matches with the Qualifier.

If the Qualifier is a computer name, the server MUST return all treeconnects made from the specified computer to the server by returning only the entries where ServerName matches with the Qualifier.

If the Qualifier parameter is a NULL (zero-length) string, or if the length of the Qualifier parameter (including the terminating null character) is greater than 1,024, the server MUST fail the call with ERROR_INVALID_PARAMETER.

The Qualifier parameter plays no role in determining the value of ResumeHandle. The server uses the ResumeHandle parameter to start the enumeration (as described in the processing rules that follow for the ResumeHandle parameter), and then applies the Qualifier parameter, if specified, to restrict the returned results to only those items that pass the qualifier test (as described previously in this topic for Qualifier) for share name or computer name.

The InfoStruct parameter has a Level member. The valid values of Level are 0 and 1. If the Level member is not equal to one of the valid values, the server MUST fail the call with ERROR_INVALID_LEVEL.

If the Level member is 0, the server MUST return the information about treeconnects by filling the CONNECT_INFO_0_CONTAINER structure in the ConnectInfo field of the InfoStruct parameter as follows. The CONNECT_INFO_0_CONTAINER structure contains an array of CONNECTION_INFO_0 structures.

  • coni0_id MUST be set to treeconnect.GlobalTreeConnectId.

If the Level member is 1, the server MUST return the treeconnects by filling the CONNECT_INFO_1_CONTAINER structure in the ConnectInfo field of the InfoStruct parameter. The CONNECT_INFO_1_CONTAINER structure contains an array of CONNECTION_INFO_1 structures.

The PreferedMaximumLength parameter specifies the maximum number of bytes that the server can return for the ConnectInfo buffer. If PreferedMaximumLength is insufficient to hold all the entries, the server MUST return the maximum number of entries that will fit in the ConnectInfo buffer and return ERROR_MORE_DATA. If this parameter is equal to MAX_PREFERRED_LENGTH, the server MUST return all the requested data.

If the server returns NERR_Success or ERROR_MORE_DATA, it MUST set the TotalEntries parameter to equal the total number of entries passing the qualifier filter that could have been enumerated from the current resume position.

If PreferedMaximumLength is insufficient to hold all the entries and if the client has specified a ResumeHandle parameter, the server MUST set ResumeHandle to some implementation-specific value that allows the server to continue with this enumeration in the TreeConnectList on a subsequent call to this method with the same value for the ResumeHandle parameter.

The following rules specify processing of the ResumeHandle parameter:

  • If the ResumeHandle parameter is either NULL or points to 0x00000000, the enumeration MUST start from the beginning of the TreeConnectList.

  • If the ResumeHandle parameter points to a nonzero value, the server MUST validate the ResumeHandle.

    • If the value of ResumeHandle is less than the size of the TreeConnectList, the server MUST continue enumeration based on the value of ResumeHandle. The value of ResumeHandle specifies the index value in the TreeConnectList after which enumeration is to begin.

    • If the value of ResumeHandle is greater than or equal to the size of the TreeConnectList, the server MUST return NERR_Success and zero entries. fail the call with ERROR_INVALID_PARAMETER.

  • If the client specified a ResumeHandle and if the server returns ERROR_MORE_DATA (0x000000EA), the server MUST set ResumeHandle to the index value of the last enumerated treeconnect in the TreeConnectList.

Because the ResumeHandle specifies the index into the TreeConnectList, and the TreeConnectList can be modified between multiple requests, the results of a query spanning multiple requests using the ResumeHandle can be unreliable, resulting in either duplicate or missed active treeconnects.

The server SHOULD<44> enforce security measures to verify that the caller has the required permissions to execute this routine. If the caller does not have the required credentials, the server SHOULD<45> fail the call.