Share via

3.1.4.1.75 FAX_SetArchiveConfiguration (Opnum 42)

  • Article

The fax client application calls the FAX_SetArchiveConfiguration (Opnum 42) method to set the archive configuration for a specific fax folder on the fax server.

In response, the server MUST validate that the client's fax user account has access to manage server configuration. On success, the server MUST set the specified configuration and return success.

Protocol version FAX_API_VERSION_3 (0x00030000) fax servers SHOULD fail this call by returning ERROR_NOT_SUPPORTED (0x00000032). The fax client SHOULD NOT call this method if the protocol version reported by the server is FAX_API_VERSION_3 (0x00030000). For more information, see FAX_ConnectFaxServer (section 3.1.4.1.10). The fax client SHOULD call FAX_SetGeneralConfiguration (section 3.1.4.1.80) instead.

 error_status_t FAX_SetArchiveConfiguration(
   [in] handle_t hFaxHandle,
   [in] FAX_ENUM_MESSAGE_FOLDER Folder,
   [in, ref] const LPBYTE pArchiveCfg
 );

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.

Folder: The archive location. The client MUST set this parameter to either FAX_MESSAGE_FOLDER_INBOX or FAX_MESSAGE_FOLDER_SENTITEMS.

pArchiveCfg: A pointer to a buffer containing an array of FAX_ARCHIVE_CONFIGW (section 2.2.27) structures. If the size of the archive exceeds the dwSizeQuotaHighWatermark value and if the bSizeQuotaWarning member is set to TRUE, an event log warning SHOULD be issued. If an event log warning was already issued, no more events SHOULD be issued until the size of the archive drops below the dwSizeQuotaLowWatermark value. If a fax message stays in the archive longer than the dwAgeLimit value, it MAY be automatically deleted. If the dwAgeLimit value is zero, the time limit MUST NOT be used.

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 (section 2.2.52), or one of the other standard errors ([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 required FAX_ACCESS_MANAGE_CONFIG authorization for this operation.

ERROR_NOT_SUPPORTED

0x00000032

The fax server does not support this operation. This error code SHOULD be returned by the FAX_API_VERSION_3 servers.

ERROR_INVALID_PARAMETER

0x00000057

The parameter is incorrect. This error code is returned under any of the following conditions:

§ The dwSizeOfStruct member of the FAX_ARCHIVE_CONFIGW specified by the pArchiveCfg parameter is set to an incorrect value.

§ The Folder parameter is set to a value other than FAX_MESSAGE_FOLDER_SENTITEMS and FAX_MESSAGE_FOLDER_INBOX.

§ The bUseArchive member of the FAX_ARCHIVE_CONFIGW specified by pArchiveCfg is set to TRUE, and any of the three following conditions are also met:

§ The value of the dwSizeQuotaHighWatermark member of the same structure is smaller than the value of the dwSizeQuotaLowWatermark member.

§ The lpcstrFolder member of the same structure is set to NULL.

§ The lpcstrFolder member of the same structure is set to point to an empty character string.

ERROR_BUFFER_OVERFLOW

0x0000006F

The file name is too long. The bUseArchive member of the FAX_ARCHIVE_CONFIGW specified by pArchiveCfg is set to a value of TRUE, and the length of the file name specified by the lpcstrFolder of the same structure is set to a character string longer than 180 characters, excluding the length of the null terminator.

ERROR_REGISTRY_CORRUPT

0x000003F7

The fax server cannot store the new archive configuration to the registry. The registry could be corrupted.

FAX_ERR_DIRECTORY_IN_USE

0x00001B5F

The bUseArchive member of the FAX_ARCHIVE_CONFIGW specified by pArchiveCfg is set to a value of TRUE, and the file specified by the lpcstrFolder member of the same structure is invalid: the directory of the file is the same as the fax queue directory.

FAX_ERR_FILE_ACCESS_DENIED

0x00001B60

The bUseArchive member of the FAX_ARCHIVE_CONFIGW specified by pArchiveCfg is set to a value of TRUE, and the file specified by the lpcstrFolder member of the same structure is invalid: the fax server encountered an access denied (ERROR_ACCESS_DENIED) or a sharing violation (ERROR_SHARING_VIOLATION) error when attempting to access the file.

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