3.1.4.24 NetrServerTransportEnum (Opnum 26)

  • Article

The NetrServerTransportEnum method enumerates the information about transport protocols that the server manages in TransportList.

 NET_API_STATUS NetrServerTransportEnum(
   [in, string, unique] SRVSVC_HANDLE ServerName,
   [in, out] LPSERVER_XPORT_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.

InfoStruct: A pointer to a structure, in the format of a SERVER_XPORT_ENUM_STRUCT structure that receives the data. The SERVER_XPORT_ENUM_STRUCT structure has a Level member that specifies the type of the structure to return in the XportInfo member. The Level member MUST be set to one of the values in section 2.2.4.101 (excluding SERVER_XPORT_INFO_3_CONTAINER).

PreferedMaximumLength: Specifies the preferred maximum length, in bytes, of 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 can be enumerated if the buffer is large enough to hold all the entries.

ResumeHandle: A pointer to a value that contains a handle that is used to continue an existing connection search. The handle MUST be zero on the first call and remain unchanged for subsequent calls. If the ResumeHandle parameter is NULL, no resume handle MUST 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 list of the currently active connections.

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. The most common error codes are listed in the following table.

Return value/code

Description

0x00000000

NERR_Success

The client request succeeded.

0x0000007C

ERROR_INVALID_LEVEL

The system call level is not correct.

0x000000EA

ERROR_MORE_DATA

The client request succeeded. More entries are available. Not all entries could be returned in the buffer size that is specified by PreferedMaximumLength.

0x00000008

ERROR_NOT_ENOUGH_MEMORY

Not enough storage is available to process this command.

0x0000084B

NERR_BufTooSmall

The client request succeeded. More entries are available. The buffer size that is specified by PreferedMaximumLength was too small to fit even a single entry.

In response to the NetrServerTransportEnum request, the server MUST enumerate the Transports from the TransportList or return an error code.

The InfoStruct parameter has a Level member. The value of Level MUST be 0, 1, or 2. If the Level member is not equal to one of the valid values, the server MUST fail the call with an ERROR_INVALID_LEVEL error code.

If the value of the Level member is 0, the server MUST return the information about the transport protocols that it is managing by filling the SERVER_XPORT_INFO_0_CONTAINER structure in the XportInfo member of the InfoStruct parameter.

If the Level member is 1, the server MUST return the information about the transport protocols that it is managing by filling the SERVER_XPORT_INFO_1_CONTAINER structure in the XportInfo member of the InfoStruct parameter.

The PreferedMaximumLength parameter specifies the maximum number of bytes that the server can return for the XportInfo buffer.

If the PreferedMaximumLength is insufficient to hold all the entries, the server MUST return the maximum number of entries that can fit in the XportInfo 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 equal to the total number of entries that could have been enumerated from the current resume position.

If the 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 on a subsequent call to this method with the same value for ResumeHandle.

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

  • If the ResumeHandle parameter points to a nonzero value, the server MUST continue enumeration based on the value of ResumeHandle. The value of ResumeHandle specifies the index into the TransportList after which the enumeration is to begin.

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

Because the ResumeHandle parameter specifies an offset into the list, and the list of all available transports can be modified between multiple requests, the results of a query spanning multiple requests using ResumeHandle can be unreliable, offering either duplicate or unavailable transports.

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