FaxRegisterRoutingExtension

The FaxRegisterRoutingExtension function registers a fax routing extension dynamic-link library (DLL) with the fax service. The function configures the fax service registry to use the new routing extension DLL. FaxRegisterRoutingExtension calls the FAX_ROUTING_INSTALLATION_CALLBACK function once for each fax routing method in the fax routing extension DLL.

Because the FaxRegisterRoutingExtension function modifies the registry, the user, generally a system administrator, must have write access to the HKEY_LOCAL_MACHINE registry key. An application can call the function only when using a local connection to the fax service.

BOOL WINAPI FaxRegisterRoutingExtension(
  HANDLE FaxHandle,       // handle to the fax server
  LPCWSTR ExtensionName,  // fax routing extension DLL name
  LPCWSTR FriendlyName,   // fax routing extension user-friendly name
  LPCWSTR ImageName,      // path to fax routing extension DLL
  PFAX_ROUTING_INSTALLATION_CALLBACK CallBack, // pointer to fax 
                          // routing installation callback function
  LPVOID Context          // pointer to context information
);

Parameters

FaxHandle

[in] Specifies a fax server handle returned by a call to the FaxConnectFaxServer function.

ExtensionName

[in] Pointer to a constant null-terminated Unicode character string that specifies the internal name of the fax routing extension DLL.

FriendlyName

[in] Pointer to a constant null-terminated Unicode character string to associate with the fax routing extension DLL. This is the routing extension's user-friendly name, suitable for display.

ImageName

[in] Pointer to a constant null-terminated Unicode character string that specifies the full path and file name for the fax routing extension DLL. The path can include valid environment variables, for example, %SYSTEMDRIVE% and %SYSTEMROOT%.

CallBack

[in] Pointer to a FAX_ROUTING_INSTALLATION_CALLBACK function that installs a fax routing method for the specified fax routing extension DLL. The FaxRegisterRoutingExtension function calls the FAX_ROUTING_INSTALLATION_CALLBACK function multiple times, until it returns a value of zero, indicating that all routing methods in the fax routing extension DLL have been registered.

Context

[in] Pointer to a variable that contains application-specific context information or an application-defined value. FaxRegisterRoutingExtension passes this data to the FAX_ROUTING_INSTALLATION_CALLBACK function.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError can return one of the following errors.

Remarks

All parameters to the FaxRegisterRoutingExtension function are required.

Local installation of a fax routing extension is recommended. The local installation routine for a fax routing extension DLL can call FaxRegisterRoutingExtension instead of directly accessing the registry. You must restart the fax service to use a fax routing method exported by a fax routing extension you install using FaxRegisterRoutingExtension.

For more information about the steps required to register locally with the fax service, see Local Registration of a Fax Routing Extension.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable with BackOffice Small Business Server.
  Header: Declared in Winfax.h.
  Library: Included as a resource in Winfax.dll.
  Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Fax Service Client Application Programming Interface Overview, Fax Service Client API Functions, FaxConnectFaxServer, FAX_ROUTING_INSTALLATION_CALLBACK