3.1.4.1.39 FAX_GetExtensionData (Opnum 49)

The FAX_GetExtensionData (Opnum 49) method is called by the client to retrieve the private configuration data for a fax routing extension or a routing method. Such private configuration data is written with a FAX_SetExtensionData (section 3.1.4.1.79) call. The lpcwstrNameGUID parameter MUST be for a valid routing extension or routing method for which the client requests the private data. The value for the dwDeviceId parameter can be obtained from either the FAX_EnumPorts (section 3.1.4.1.28) or the FAX_EnumPortsEx (section 3.1.4.1.29) methods.

In response, the server MUST validate that the client's fax user account has the access rights required to query the configuration data. It MUST then allocate memory for the routing extension data to be passed out and fill it with data.

To indicate success, the server MUST return the buffer that contains the routing extension data, along with the buffer size.

The client SHOULD free the buffer.

 error_status_t FAX_GetExtensionData(
   [in] handle_t hFaxHandle,
   [in] DWORD dwDeviceId,
   [in, string, ref] LPCWSTR lpcwstrNameGUID,
   [out, size_is(, *lpdwDataSize)] 
     LPBYTE* ppData,
   [out, ref] LPDWORD lpdwDataSize
 );

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.

dwDeviceId: The device identifier. A value of zero indicates the caller requests 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 would become global.

lpcwstrNameGUID: A curly-braced GUID string that identifies the data to return. 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 routing extension data or routing method data.

ppData: A pointer to an allocated private data buffer. This buffer contains the data that is returned by the fax server. For the default routing methods described in 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.

lpdwDataSize: A pointer to a DWORD ([MS-DTYP] section 2.2.9) value that returns the size, in bytes, of the data that is pointed to by the ppData parameter.

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_FILE_NOT_FOUND 0x00000002	The fax server cannot find the requested data.
ERROR_ACCESS_DENIED 0x00000005	Access is denied. The client's fax user account does not have the access rights (FAX_ACCESS_QUERY_CONFIG) required for this operation.
ERROR_INVALID_PARAMETER 0x00000057	The parameter is incorrect. This error code is returned if any of the following conditions are met: <109> § The lpcwstrNameGUID parameter is set to a NULL pointer value. § The ppData parameter is set to a NULL pointer value. § The lpdwDataSize parameter is set to a NULL pointer value. § 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].