DTWAIN_SetPDFEncryption

The following function is available only with DTWAIN / PDF.

The DTWAIN_SetPDFEncryption sets the encryption level for a PDF file.

DTWAIN_BOOL DTWAIN_SetPDFEncryption (

DTWAIN_SOURCE	Source,
DTWAIN_BOOL	bEncryptFile,
LPCTSTR	lpszUserPassword,
LPCTSTR	lpszOwnerPassword,
LONG	Permissions,
DTWAIN_BOOL	Use128BitEncryption );

Parameters

Source

An open TWAIN Source.

bEncryptFile

Denotes whether encryption is turned on or off when creating the PDF file.

lpszUserPassword

Pointer to PDF User password string. Ignored if bEncryptFile is FALSE.

lpszOwnerPassword

Pointer to PDF Owner password string. Ignored if bEncryptFile is FALSE.

Permissions

Integer denoting the various permissions allowed to the user of the PDF file. Ignored if bEncryptFile is FALSE.

Use128BitEncryption

Denotes usage of 128-bit (strong) encryption, or 40-bit encryption. Ignored if bEncryptFile is FALSE

Return Values

The return value is TRUE if successful. Otherwise FALSE is returned.

Character specific version

ANSI version:	DTWAIN_SetPDFEncryptionA
Unicode version:	DTWAIN_SetPDFEncryptionW

Comments

The DTWAIN_SetPDFEncryption is used to enable or disable encryption when creating a PDF file. An encrypted PDF file is one where most of the contents of the file are encrypted, and requires decryption for an application to interpret the contents. An advantage of an encrypted PDF file is that changing the contents of an ecrypted PDF file using a binary file editor, for example, is virtually impossible without corrupting the entire PDF file. On the other hand, with an unencrypted PDF file, changing the contents (for example, the Creator or Author fields) is trivial with a binary file editor.

If the bEncryptFile parameter is FALSE, encryption is turned off, and the other following parameters are ignored. If bEncryptFile is TRUE, the other following parameters control the passwords, permissions, and whether strong encryption is used. By default, encryption is turned off when creating PDF files.

An encrypted PDF file has a maximum of two passwords, a user password and an owner password. If the user or owner password is present, opening the PDF file in Adobe Acrobat requires one of these password to be entered. Note that a PDF file that is encrypted does not have to have a user or an owner password, thereby allowing the encrypted PDF file to be opened in Acrobat without entering a password. The passwords can have a maximum length of 32 characters.

The owner password allows changes to the PDF file's password settings and other settings deemed secure. If an owner password is present, the user must enter the owner password when prompted by the Adobe Acrobat program to allow changes to the PDF file's security settings.

To summarize:

•	If a user password exists, but no owner password exists, the user can set the permissions in the file.

•	If a user password and an owner password exists, the user cannot set the permissions -- only the owner can change these settings.

•	If only an owner password is present, the owner can change the permissions.

•	If no owner and no user password exists, the PDF file can be opened in Adobe Acrobat Reader without entering a password (however, the file is still encrypted, even though anyone can open and view the file).

The user password is denoted by the lpszUserPassword parameter. This can either be an array of characters, or NULL to denote no user password. Also acceptable is an empty string, which would denote no user password. The user password allows persons to open the PDF file, but will not allow them to change the permissions on the PDF file if there is an owner password.

The owner password is denoted by the lpszOwnerPassword parameter. This can either be a NULL terminated array of characters, or NULL to denote no owner password. Also acceptable is an empty string, which would denote no owner password.

The Permissions parameter controls what actions are allowed on the PDF file. These values are simply boolean OR'ed or added together to form the entire permission value. The list of permissions are as follows:

Permission	Description
DTWAIN_PDF_ALLOWPRINTING	Allows printing PDF file.
DTWAIN_PDF_ALLOWMOD	Allow modification of PDF file.
DTWAIN_PDF_ALLOWCOPY	Allows copying and text extraction of PDF file.
DTWAIN_PDF_ALLOWMODANNOTATIONS	Allows modification of the PDF annotations.
DTWAIN_PDF_ALLOWFILLIN	Allows fill-in of interactive form fields (Strong encryption only).
DTWAIN_PDF_ALLOWEXTRACTION	Allows text extraction (in support of accessibility to disabled users or for other purposes) (Strong encryption only)
DTWAIN_PDF_ALLOWASSEMBLY	Allow Assembly of the document (insert, rotate, or delete pages and create bookmarks or thumbnail images) (Strong encryption only)
DTWAIN_PDF_ALLOWDEGRADEDPRINTING	Allows printing a documented with degraded print quality (Strong encryption only).

The Use128BitEncryption denotes whether 128-bit (strong) encryption will be used when encrypting the document, or whether 40-bit encryption will be used. If Use128BitEncryption is TRUE, 128-bit encryption is used, otherwise 40-bit encryption is used.

Example:

Encrypt PDF files using the user password "test" and owner password "test2". Allow the documented to be printed and copied. Use strong encryption:

DTWAIN_SetPDFEncryption( Source, TRUE, "test", "test2", DTWAIN_PDF_ALLOWPRINTING + DTWAIN_PDF_ALLOWCOPY, TRUE);

Turn off PDF encryption:

DTWAIN_SetPDFEncryption( Source, FALSE, "", "", 0, FALSE);

Encrypt PDF files using no user password, owner password "test2". Allow the documented to be printed and copied. Use strong encryption:

DTWAIN_SetPDFEncryption( Source, TRUE, "", "test2", DTWAIN_PDF_ALLOWPRINTING + DTWAIN_PDF_ALLOWCOPY, TRUE);

or the following is acceptable:

DTWAIN_SetPDFEncryption( Source, TRUE, NULL, "test2", DTWAIN_PDF_ALLOWPRINTING + DTWAIN_PDF_ALLOWCOPY, TRUE);

Encrypt PDF file, but do not have user or owner passwords. Allow the documented to be printed and copied. Use normal encryption:

DTWAIN_SetPDFEncryption( Source, TRUE, "", "", DTWAIN_PDF_ALLOWPRINTING + DTWAIN_PDF_ALLOWCOPY, FALSE);

TWAIN State Transitions

The Source must be in State 4. or higher

Prerequisite Function Call(s)

DTWAIN_SysInitialize

DTWAIN Source Selection Function