3.2.4.21 NetrEnumerateComputerNames (Opnum 30)

  • Article

The NetrEnumerateComputerNames method returns a list of computer names for a specified server (2). The results of the query are determined by the type of the name. <120>

 unsigned long NetrEnumerateComputerNames(
   [in, string, unique] WKSSVC_IMPERSONATE_HANDLE ServerName,
   [in] NET_COMPUTER_NAME_TYPE NameType,
   [in] unsigned long Reserved,
   [out] PNET_COMPUTER_NAME_ARRAY* ComputerNames
 );

ServerName: A WKSSVC_IMPERSONATE_HANDLE structure (section 2.2.2.2) that specifies the server. 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.

NameType: The type of query issued. See NET_COMPUTER_NAME_TYPE (section 2.2.3.3).

Reserved: A 32-bit bitfield that SHOULD be set to zero.


0


1


2


3


4


5


6


7


8


9

1
0


1


2


3


4


5


6


7


8


9

2
0


1


2


3


4


5


6


7


8


9

3
0


1

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

IU

Where the bits are defined as:

Value

Meaning

IU

NET_IGNORE_UNSUPPORTED_FLAGS

If 1, the server MUST ignore the values of the other bits in this field.

If 0, the values of the other bits in this field MUST be 0; otherwise, the server MUST return ERROR_INVALID_FLAGS. <121>

ComputerNames: A pointer to structure containing a list of computer name strings. See NET_COMPUTER_NAME_ARRAY (section 2.2.5.21).

Return Values: When the message processing result meets 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_NOT_ENOUGH_MEMORY

0x00000008

Not enough storage is available to process this command.

ERROR_INVALID_PARAMETER

0x00000057

The parameter is incorrect.

ERROR_NOT_SUPPORTED

0x00000032

This method is not supported by this server.

ERROR_INVALID_FLAGS

0x000003EC

Reserved contains an invalid value.

RPC_S_PROTSEQ_NOT_SUPPORTED

0x000006A7

The RPC protocol sequence is not supported.

RPC_S_CALL_IN_PROGRESS

0x000006FF

A remote procedure call is already in progress.

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

The following statements define the sequence of message processing operations.

  1. The server MUST retrieve the RPC protocol sequence used for the current call ([MS-RPCE] section 3.1.3.4.1), specifying the server binding handle maintained by the RPC runtime ([C706] section 6.2.1). If that RPC protocol sequence is not NCACN_NP, the server SHOULD return RPC_S_PROTSEQ_NOT_SUPPORTED.<122>

  2. The server MUST check that the caller has been granted access rights using the algorithm in the Access Control Abstract Data Model (section 3.2.1.1), with Access Request mask initialized to WKSTA_NETAPI_CHANGE_CONFIG; if not, the server MUST return ERROR_ACCESS_DENIED.

  3. The server SHOULD<123> return ERROR_NOT_SUPPORTED if the server is a client SKU configuration.

  4. The server MUST return ERROR_INVALID_PARAMETER if NameType is greater than or equal to NetComputerNameTypeMax.

  5. The server MUST impersonate the client by invoking the StartImpersonatingClient task (section 3.2.4.29.6). If this operation fails, the server MUST return an error.

  6. The server MUST initialize the output parameter ComputerNames as follows depending on the input query type in NameType.

    • NetPrimaryComputerName:

      The server MUST set ComputerNames.EntryCount to 1 and initialize the UNICODE_STRING values in ComputerNames to ComputerNameFQDN (section 3.2.1.5).

    • NetAlternateComputerNames:

      The server MUST set ComputerNames.EntryCount to the number of tuples contained in alternate-computer-names (section 3.2.1.2). For each tuple, I, the server MUST initialize the next available UNICODE_STRING elements in the ComputerNames array to equal the values stored in alternate-computer-names[I].FQDN.

    • NetAllComputerNames:

      The server MUST set ComputerNames.EntryCount to the number of tuples contained in alternate-computer-names + 1. The ComputerNames array MUST be initialized to return all the names specified for the NetPrimaryComputerName and NetAlternateComputerNames input query types.

  7. The server MUST stop impersonating the client by invoking the StopImpersonatingClient task (section 3.2.4.29.7).

If no errors occur, the server MUST return NERR_Success.