3.1.4.1.69 FAX_RegisterServiceProviderEx (Opnum 60)

The fax client application calls the FAX_RegisterServiceProviderEx (Opnum 60) method to register a fax service provider (FSP) with the Fax Service. Registration takes place after the Fax Service restarts.

In response, the server MUST validate that the client's fax user account has access to register an FSP. The server MUST also validate that the guidlpcwstrGUID is not a duplicate because it MUST NOT register duplicate FSPs.

On success, the server MUST register the specified FSP.

 error_status_t FAX_RegisterServiceProviderEx(
   [in] handle_t hFaxHandle,
   [in, string, ref] LPCWSTR lpcwstrGUID,
   [in, string, ref] LPCWSTR lpcwstrFriendlyName,
   [in, string, ref] LPCWSTR lpcwstrImageName,
   [in, string, ref] LPCWSTR lpcwstrTspName,
   [in] DWORD dwFSPIVersion,
   [in] DWORD dwCapabilities
 );

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.

lpcwstrGUID: A pointer to a constant null-terminated character string that contains a valid string representation of the GUID of the FSP.

lpcwstrFriendlyName: A pointer to a constant null-terminated character string to associate with the FSP execution component. This is the FSP friendly name, which is suitable for display. This value cannot exceed MAX_FAX_STRING_LEN (section 2.2.86) characters.

lpcwstrImageName: A pointer to a constant null-terminated character string that specifies the full path and file name for the FSP execution component.<148> This value cannot exceed MAX_FAX_STRING_LEN characters.

lpcwstrTspName: A pointer to a constant null-terminated character string that specifies the name of the telephony service provider that is associated with the devices for the FSP. This parameter SHOULD be set to NULL if the FSP does not use a telephony service provider. This value cannot exceed MAX_FAX_STRING_LEN characters. This value MUST be unique across all registered FSPs.

dwFSPIVersion: A DWORD ([MS-DTYP] section 2.2.9) value that specifies the API version of the FSP interface. The value MUST be 0x00010000.

dwCapabilities: A DWORD value that specifies the capabilities of the extended FSP. This value MUST be 0.

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 authorization for FAX_ACCESS_MANAGE_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: § The lpcwstrGuid parameter contains an invalid GUID. § The dwFSPIVersion parameter is set to a value other than 0x00010000. § The dwCapabilities parameter is set to a value other than 0. § The file path specified by the lpcwstrImageName parameter does not exist, or the fax server does not have access to the file.
ERROR_BUFFER_OVERFLOW 0x0000006F	The length of the lpcwstrFriendlyName, lpcwstrImageName or lpcwstrTspName character strings exceeds MAX_FAX_STRING_LEN characters, excluding the length of the NULL string terminator.
ERROR_ALREADY_EXISTS 0x000000B7	An FSP is already registered with the same GUID (specified by the lpcwstrGUID parameter) or with the same telephony service provider (specified by the lpcwstrTspName parameter).
ERROR_REGISTRY_CORRUPT 0x000003F7	The registry is corrupted. The structure of one of the files that contains 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].