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].