3.1.4.45 NetrServerAliasEnum (Opnum 55)

  • Article

The NetrServerAliasEnum method retrieves alias information for a server based on specified alias name or server name.

 NET_API_STATUS NetrServerAliasEnum(
   [in, string, unique] SRVSVC_HANDLE ServerName,
   [in, out] LPSERVER_ALIAS_ENUM_STRUCT InfoStruct,
   [in] DWORD PreferedMaximumLength,
   [out] LPDWORD TotalEntries,
   [in, out, unique] LPDWORD 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_ALIAS_ENUM_STRUCT, as specified in section 2.2.4.104. The SERVER_ALIAS_ENUM_STRUCT structure has a Level member that specifies the type of structure to return in the ServerAliasInfo member. The Level member MUST be one of the values specified in section 2.2.4.104.

PreferedMaximumLength: Specifies the preferred maximum length, in bytes, of the returned data. If the specified value is MAX_PREFERRED_LENGTH, 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, which is used to continue an existing alias search in AliasList. 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 AliasList.

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.

0x00000005

ERROR_ACCESS_DENIED

Access is denied.

0x00000057

ERROR_INVALID_PARAMETER

The client request failed because the specified parameter is invalid.

0x00000008

ERROR_NOT_ENOUGH_MEMORY

Not enough storage is available to process this command.

0x0000084B

NERR_BufTooSmall

The allocated buffer is too small to hold single entry.

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.

In response to a NetrServerAliasEnum message, the server MUST return information about each alias resource on a server, or return an error code.

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

If the Level member is 0, the server MUST return the information about aliases by filling the SERVER_ALIAS_INFO_0_CONTAINER structure in the ServerAliasInfo member of the InfoStruct parameter. The SERVER_ALIAS_INFO_0_CONTAINER structure contains an array of SERVER_ALIAS_INFO_0 structures.

The PreferedMaximumLength parameter specifies the maximum number of bytes that the server can return for the ServerAliasInfo buffer. If PreferedMaximumLength is insufficient to hold all the entries, the server MUST return the maximum number of entries as will fit in the ServerAliasInfo 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 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, 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 server MUST maintain AliasList.

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

  • 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 AliasList 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 alias in the AliasList.

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

The server SHOULD<173> 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<174> fail the call.