3.2.4.4 NetrWkstaTransportEnum (Opnum 5)

  • Article

The NetrWkstaTransportEnum method provides details about the transport protocols currently enabled for use by the SMB network redirector on a remote computer.

 unsigned long NetrWkstaTransportEnum(
   [in, string, unique] WKSSVC_IDENTIFY_HANDLE ServerName,
   [in, out] LPWKSTA_TRANSPORT_ENUM_STRUCT TransportInfo,
   [in] unsigned long PreferredMaximumLength,
   [out] unsigned long* TotalEntries,
   [in, out, unique] unsigned long* ResumeHandle
 );

ServerName: A WKSSVC_IDENTIFY_HANDLE structure (section 2.2.2.1) that identifies the server (2). The client MUST map this structure to an RPC binding handle ([C706] sections 4.3.5 and 5.1.5.2). The server MUST ignore this parameter.

TransportInfo: A pointer to a buffer that receives a WKSTA_TRANSPORT_ENUM_STRUCT structure (section 2.2.5.16), which contains a Level member that MUST be set to zero.

PreferredMaximumLength: The number of bytes to allocate for the return data.

TotalEntries: The total number of entries that could have been enumerated from the current resume position. This field can be set to any value when sent and MUST be ignored on receipt.

ResumeHandle: A pointer that, if specified, and if this method returns NERR_BufTooSmall, MUST receive an implementation-specific value<37> that can be passed in subsequent calls to this method, to continue with the enumeration of currently enabled transport protocols.

If this parameter is NULL or points to zero, the enumeration MUST start from the beginning of the list of currently enabled transport protocols.

Return Values: When the message processing result matches the description in column two of the following table, this method MUST return one of the following values ([MS-ERREF] section 2.2).

Value/code

Meaning

NERR_Success

0x00000000

The operation completed successfully.

ERROR_ACCESS_DENIED

0x00000005

Access is denied.

ERROR_INVALID_LEVEL

0x0000007C

The information level is invalid.

NERR_BufTooSmall

0x0000084B

More entries are available. The TransportInfo buffer was not large enough to contain all the entries.

Any other return value MUST conform to the error code requirements in Protocol Details (section 3).

The server SHOULD<38> enforce security measures to verify that the caller has the required permissions to execute this routine. If the server enforces security measures, and the caller does not have the required credentials, the server MUST fail the call with ERROR_ACCESS_DENIED. Specifications for determining the identity of the caller for the purpose of performing an access check are in [MS-RPCE] section 3.3.3.1.3.

For any other conditions, this method MUST return any other value, and the client MUST treat all other values the same.

If the Level member in the WKSTA_TRANSPORT_ENUM_STRUCT structure passed in the TransportInfo parameter does not equal 0x00000000, the server MUST fail the call.

If the Level member is 0x00000000, the server MUST return an array of details about the transport protocols currently enabled for use by the SMB network redirector by filling the WKSTA_TRANSPORT_INFO_0_CONTAINER structure WkstaTransportInfo member (section 2.2.5.15) of the TransportInfo parameter for each transport in TransportList (section 3.2.1.4), as follows:

  • wkti0_transport_address set to Transport.Address

  • wkti0_transport_name set to Transport.Name

  • wkti0_number_of_vcs set to Transport.VC_Count

  • wkti0_wan_ish set to Transport.Wannish

If the PreferredMaximumLength parameter equals MAX_PREFERRED_LENGTH (section 2.2.1.3), the server MUST return all the requested data. If the PreferredMaximumLength is insufficient to hold all the entries, the server MUST return the maximum number of entries that fit in the TransportInfo buffer and return NERR_BufTooSmall.

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 list of the currently enabled transport protocols. <39>

  • If the ResumeHandle parameter is nonzero, the server MUST begin enumeration based on the value of ResumeHandle. The server is not required to maintain any state between calls invoking the NetrWkstaTransportEnum method.

  • If the client specified a ResumeHandle, and if the server returns NERR_BufTooSmall, the server MUST set ResumeHandle to an implementation-specific value that allows the server to continue with this enumeration on a subsequent call to this method, using the same value for ResumeHandle.

The server is not required to maintain any state between calls to the NetrWkstaTransportEnum method. If the server returns NERR_Success, it MUST set the TotalEntries parameter to equal the total number of entries that could have been enumerated from the current resume position. If the server returns NERR_BufTooSmall, it SHOULD set the TotalEntries value to the total number of entries that could have been enumerated from the current resume position.<40>