3.1.4.2.1 RpcEnumPrinters (Opnum 0)

RpcEnumPrinters enumerates available printers, print servers, domains, or print providers.

 DWORD RpcEnumPrinters(
   [in] DWORD Flags,
   [in, string, unique] STRING_HANDLE Name,
   [in] DWORD Level,
   [in, out, unique, size_is(cbBuf), disable_consistency_check] 
     BYTE* pPrinterEnum,
   [in] DWORD cbBuf,
   [out] DWORD* pcbNeeded,
   [out] DWORD* pcReturned
 );

Flags: The types of print objects that this method enumerates. The value of this parameter is the result of a bitwise OR of one or more of the Printer Enumeration Flags (section 2.2.3.7), with the following additional specifications:

• PRINTER_ENUM_NAME: If the Name parameter is NULL or points to an empty string, and the Level parameter value is 0x00000001, available print providers SHOULD be enumerated. If this flag is not set, the server SHOULD ignore the Name parameter.

• PRINTER_ENUM_REMOTE: The Level parameter value MUST be 0x00000001.

• PRINTER_ENUM_NETWORK: The Level parameter value MUST be 0x00000001.

Name: NULL or a server name parameter as specified in Printer Server Name Parameters (section 3.1.4.1.4). If the Flags parameter contains the PRINTER_ENUM_NAME flag, the Name parameter value controls where the server SHOULD enumerate. The server SHOULD enumerate locally if the Name parameter is either NULL or an empty string; otherwise, remotely on the server whose name is specified by the Name string.

Level: The level of printer information structure, as follows.

Value	Description
0x00000000	_PRINTER_INFO_STRESS (section 2.2.2.9.1)
0x00000001	_PRINTER_INFO_1 (section 2.2.2.9.2)
0x00000002	_PRINTER_INFO_2 (section 2.2.2.9.3)
0x00000004	_PRINTER_INFO_4 (section 2.2.2.9.5)
0x00000005	_PRINTER_INFO_5 (section 2.2.2.9.6)

pPrinterEnum: A pointer to a BUFFER defined in INFO Structures Query Parameters (section 3.1.4.1.9).

BUFFER TYPE: PRINTER_INFO.

This parameter can be NULL if the value of cbBuf is zero.

cbBuf: An input parameter that adheres to the specification in INFO Structures Query Parameters.

pcbNeeded: An output parameter that adheres to the specification in INFO Structures Query Parameters.

pcReturned: An output parameter that adheres to the specification in INFO Structures Query Parameters.

Return Values: This method MUST return zero (ERROR_SUCCESS) to indicate successful completion and SHOULD<264> return a nonzero Windows error code ([MS-ERREF] section 2.2) to indicate failure.

Upon receiving this message, the server SHOULD validate parameters as follows:

• Perform validation steps as specified in Print Server Name Parameters (section 3.1.4.1.4).

• Perform validation steps as specified in INFO Structures Query Parameters (section 3.1.4.1.9).

• If the PRINTER_ENUM_NETWORK or PRINTER_ENUM_REMOTE flag is set, verify that the value of the Level parameter is 0x00000001. Otherwise, the server SHOULD return ERROR_INVALID_LEVEL.

• Additional validation MAY<265> be performed.

If parameter validation fails, the server MUST fail the operation immediately and return a nonzero error response to the client. Otherwise, the server MUST process the message and compose a response to the client as follows:

• If the value of the Level parameter is 0x00000001 and the PRINTER_ENUM_NETWORK bit is set in the Flags parameter, the server SHOULD enumerate all printers from the "List of Known Printers" (section 3.1.1).<266>

  If the server does not maintain a list of known printers, or if the list has not contained at least one entry for an implementation-specific period of time, the server SHOULD return ERROR_CAN_NOT_COMPLETE.<267>

• For any other validated values for the Level and Flags parameters, the server SHOULD enumerate all printers in the "List of Printers" (section 3.1.1) on the print server or print provider that comply with the value of the Flags parameter. This information SHOULD be restricted for security reasons.<268>

• Using the enumerated objects, perform the processing and response steps specified in INFO Structures Query Parameters (section 3.1.4.1.9).

• Return the status of the operation.