3.1.4.12.2 RpcSetJobNamedProperty (Opnum 111)

  • Article

RpcSetJobNamedProperty creates a new Job Named Property (section 3.1.1), or changes the value of an existing Job Named Property for the specified print job.<398>

 DWORD RpcSetJobNamedProperty(
   [in] PRINTER_HANDLE hPrinter,
   [in] DWORD JobId,
   [in] RPC_PrintNamedProperty* pProperty
 );

hPrinter: A PRINTER_HANDLE (section 2.2.1.1.4) to a printer object, job object, or server object that was opened by RpcAddPrinter (section 3.1.4.2.3), RpcAddPrinterEx (section 3.1.4.2.15), RpcOpenPrinter (section 3.1.4.2.2), or RpcOpenPrinterEx (section 3.1.4.2.14).

JobId: The identifier of a print job. This value MUST NOT be zero.

pProperty: A pointer to an RPC_PrintNamedProperty (section 2.2.1.14.2) structure specifies the property to be created if it does not exist for the print job specified by the JobId parameter, or update an existing property with a new value. This pointer MUST NOT be NULL.

Return Values: This method MUST return zero (ERROR_SUCCESS) to indicate successful completion or a nonzero Windows error code to indicate failure [MS-ERREF].

Upon receiving this message, the server MUST validate the following:

  • Perform the validation steps that are specified in PRINTER_HANDLE Parameters (section 3.1.4.1.11).

  • Verify that the value of the JobId parameter corresponds to a job in the list of jobs. If the object specified by the hPrinter parameter is a server object, search for a print job in each printer in the list of printers on the print server. If the object specified by the hPrinter parameter is a printer object, search for a print job only in the list of print jobs for the specified printer. If the object specified by the hPrinter parameter is a job object, compare the identifier of this print job with the specified JobId. If this verification fails, return ERROR_INVALID_PARAMETER.

  • Verify that the RPC_PrintNamedProperty structure specified by the pProperty parameter contains an ePropertyType member set to a valid value as specified in section 2.2.1.14.3. If this verification fails, return ERROR_INVALID_FLAGS.

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 property specified by the pProperty parameter does not exist for the print job specified by the JobId parameter, create a new property with the name and value specified by the pProperty parameter.

  • If the property specified by the pProperty parameter does exist for the print job specified by the JobId parameter, update the property with the value specified by the pProperty parameter.

  • Return the status of the operation.