3.1.4.1.35 FAX_GetConfigOption (Opnum 104)

The FAX_GetConfigOption (Opnum 104) is called by the client to retrieve a configuration setting at the server using an RPC_REQUEST packet.

Protocol version FAX_API_VERSION_0 (0x00000000), FAX_API_VERSION_1 (0x00010000), and FAX_API_VERSION_2 (0x00020000) fax servers SHOULD NOT implement this call. The fax client MUST NOT call this method if the protocol version reported by the server is FAX_API_VERSION_0 (0x00000000), FAX_API_VERSION_1 (0x00010000), or FAX_API_VERSION_2 (0x00020000). For more information, see FAX_ConnectFaxServer (section 3.1.4.1.10).

In response, the server MUST validate that the client's fax user account has access as follows. Use of this method does NOT require FAX_ACCESS_QUERY_CONFIG access rights. A calling user with any access control entry (ACE) on the server can use this method.

On success, the appropriate config option MUST be passed out by the server.

 error_status_t FAX_GetConfigOption(
   [in] handle_t hFaxHandle,
   [in] FAX_ENUM_CONFIG_OPTION option,
   [out] LPDWORD lpdwValue
 );

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 or FAX_ConnectionRefCount (section 3.1.4.1.11) method call used to connect to the fax server.

option: Identifies the configuration option to be returned. This parameter MUST be a value from the FAX_ENUM_CONFIG_OPTION (section 2.2.3) enumeration.

lpdwValue: A pointer to a DWORD ([MS-DTYP] section 2.2.9) that holds the value of the configuration option upon return. The value's type depends on the configuration option that was asked for using the option parameter.

If option was set to FAX_CONFIG_OPTION_ALLOW_PERSONAL_CP, lpdwValue contains a BOOL that MUST take one of the following values.

Value/code

Meaning

TRUE

0x00000001

The server allows personal cover page templates.

FALSE

0x00000000

The server allows only server-side cover page templates.

If option was set to FAX_CONFIG_OPTION_QUEUE_STATE, lpdwValue is a DWORD value that MUST specify state information about the fax queue defined in section 3.1.1. If this value is zero, both the incoming and outgoing queues are unblocked. Otherwise, this value MUST be a combination of one or more of the following flags.

Value/code

Meaning

FAX_INCOMING_BLOCKED

0x00000001

The incoming faxes queue is blocked. The fax server does not answer any new incoming faxes.

FAX_OUTBOX_BLOCKED

0x00000002

The outbox queue is blocked. The fax server does not accept submission of new faxes. If the outbox is not paused, faxes in the queue are being processed.

FAX_OUTBOX_PAUSED

0x00000004

The outbox queue is paused. The fax server will not start sending outgoing faxes from the queue. Fax transmissions in progress are not affected. If the outbox is not blocked, the fax server still accepts submission of new faxes to the queue.

If option was set to FAX_CONFIG_OPTION_ALLOWED_RECEIPTS, lpdwValue contains a DWORD that MUST be a bitwise combination of one or more of the flags that are specified in FAX_ENUM_DELIVERY_REPORT_TYPES (section 2.2.76).

If option was set to FAX_CONFIG_OPTION_INCOMING_FAXES_PUBLIC, lpdwValue contains a BOOL that MUST take one of the following values.

Value/code

Meaning

TRUE

0x00000001

All incoming faxes can be viewed by all fax users.

FALSE

0x00000000

Incoming faxes can be viewed only by recipients.

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 any of the permissions covered by ALL_FAX_USER_ACCESS_RIGHTS.

ERROR_INVALID_PARAMETER

0x00000057

This error is returned when any of the following conditions are met:

§ The lpdwValue parameter is set to a NULL pointer value.<103>

§ The configuration option specified by the option parameter is not one of the following values: FAX_CONFIG_OPTION_ALLOW_PERSONAL_CP, FAX_CONFIG_OPTION_QUEUE_STATE, FAX_CONFIG_OPTION_ALLOW_RECEIPTS or FAX_CONFIG_OPTION_INCOMING_FAXES_PUBLIC.

Use of this method does not require FAX_ACCESS_QUERY_CONFIG access rights. A calling user with any ACE on the server can use this method.

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