3.1.4.1.79 FAX_SetExtensionData (Opnum 50)

The fax client application calls the FAX_SetExtensionData (Opnum 50) method in order to write the private data for a routing extension or routing method for one or all fax devices installed on the fax server. The corresponding method that the fax client calls to read this private data is FAX_GetExtensionData (section 3.1.4.1.39). The value for the dwDeviceId parameter can be obtained using either the FAX_EnumPorts (section 3.1.4.1.28) or FAX_EnumPortsEx (section 3.1.4.1.29) method. The lpcwstrNameGUID parameter MUST be for a valid routing extension or routing method for which the client requests the private data to be written.

In response, the server MUST validate that the client's fax user account has access to manage configuration on the server.

On success, the server MUST apply the specified private routing extension data or private routing method data for the specified device.

When routing method configuration data is specified, lpcwstrNameGUID MUST contain the GUID of the corresponding routing method.

 error_status_t FAX_SetExtensionData(
   [in] handle_t hFaxHandle,
   [in, string] LPCWSTR lpcwstrComputerName,
   [in] DWORD dwDeviceId,
   [in, string] LPCWSTR lpcwstrNameGUID,
   [in, ref, size_is(dwDataSize)] LPBYTE pData,
   [in, range(0,FAX_MAX_RPC_BUFFER)] 
     DWORD dwDataSize
 );

hFaxHandle: The RPC binding handle for this call. The client SHOULD reuse the RPC binding handle used as an input hBinding argument for the FAX_ConnectFaxServer (section 3.1.4.1.10) or FAX_ConnectionRefCount (section 3.1.4.1.11) method call used to connect to the fax server.

lpcwstrComputerName: A null-terminated character string that SHOULD hold the name of the client computer.

dwDeviceId: A DWORD ([MS-DTYP] section 2.2.9) value of the unique device identifier. A value of zero indicates the caller needs to set a named data BLOB that is not associated with any specific device. This value can be used to store configurations that affect all the devices. For example, an Optical Character Recognition (OCR) routing extension might export several different routing methods that all rely on the same OCR parameters. This routing extension can associate the OCR configuration with a non-specific device so that it becomes global.

lpcwstrNameGUID: A curly-braced GUID string that identifies the data to set. The GUID can identify a routing extension or a routing method. Because GUIDs are unique, the server determines from the specific GUID value whether the call is requesting to set routing extension data or routing method data. If some data is already set for the specified GUID, the fax server SHOULD replace it with the new data that is pointed to by the pData parameter.

pData: A pointer to the data buffer to set. For the default routing methods described in the Default Routing Methods (section 2.2.87) this data is a null-terminated character string containing an EmailID, Printer, or Folder name. For other routing extensions or methods the format of this data depends on the respective routing extension or routing method and SHOULD be treated as opaque binary data by the fax server.

dwDataSize: A DWORD value that indicates the size, in bytes, of the pData buffer. The maximum size is FAX_MAX_RPC_BUFFER (section 2.2.82).

Return Values: This method MUST return 0x00000000 (ERROR_SUCCESS) for success; otherwise, it MUST return one of the following error codes, one of the fax-specific errors that are defined in section 2.2.52, or one of the other standard errors defined in [MS-ERREF] section 2.2.

Return value/code	Description
ERROR_ACCESS_DENIED 0x00000005	Access is denied. The client's fax user account does not have the required FAX_ACCESS_MANAGE_CONFIG authorization for this operation.
ERROR_INVALID_PARAMETER 0x00000057	The parameter is incorrect. This error code is returned if any of the following conditions are met:<161> § The lpcwstrComputerName parameter is set to a NULL pointer value. § The lpcwstrNameGUID parameter is set to a NULL pointer value. § The pData parameter is set to a NULL pointer value. § The dwDataSize parameter is set to zero. § The lpcwstrNameGUID parameter holds an invalid curly-braced GUID string.
ERROR_REGISTRY_CORRUPT 0x000003F7	The registry is corrupted. The structure of one of the files that contain registry data is corrupted, or the system's memory image of the file is corrupted, or the file could not be recovered because the alternate copy or log was absent or corrupted.

Exceptions Thrown: No exceptions are thrown except those that are thrown by the underlying RPC protocol [MS-RPCE].