Foxit PDF SDK

Instance Methods | List of all members
<FSSignatureCallback> Protocol Reference

Inherits <NSObject>.

## Instance Methods
(FSSignatureCallbackCertValidity) | - checkCertificateValidity:cert_password:client_data:
| A callback function used to check the validity of a certificate. More...
(FSProgressiveState) | - continueCalcDigest:client_data:
| A callback function used to continue the custom digest calculation process. More...
(NSData *) | - getDigest:
| A callback function used to get the digest after the calculation process is finished. More...
(BOOL) | - isNeedPadData
| A callback function used to check whether to return all contents with padding zero or not, when callback function FSSignatureCallback::verifySigState:signed_data:client_data: is called. More...
(NSData *) | - sign:cert_file_stream:cert_password:digest_algorithm:client_data:
| A callback function used to do signing and return the signed data. More...
(NSData *) | - sign:cert_path:cert_password:digest_algorithm:client_data:
| A callback function used to do signing and return the signed data. More...
(BOOL) | - startCalcDigest:byte_range_array:signature:client_data:
| A callback function used to start a custom digest calculation, mainly to initialize the calculation process. More...
(FSSignatureStates) | - verifySigState:signed_data:client_data:
| A callback function used to verify the integrity of a signature and return the verify state. More...

## Detailed Description

This class represent a callback object to sign or verify signature. All the pure virtual functions in this class are used as callback functions and should be implemented by user, in order to sign or verify signature in a customized way.
User can set register customized signature callback object to Foxit PDF SDK by function FSLibrary::registerSignatureCallback:sub_filter:signature_callback: with filter and sub filter as the callback name.

See also
  FSLibrary

## Method Documentation

## ◆ checkCertificateValidity:cert_password:client_data:()

- (FSSignatureCallbackCertValidity) checkCertificateValidity: |  | (NSString *) | cert_path
cert_password: |  | (NSString *) | cert_password
client_data: |  | (void *) | client_data
| required

A callback function used to check the validity of a certificate.

This callback function will be triggered when function FSSignature::startSign:cert_password:digest_algorithm:save_path:client_data:pause: is called. If no need to check the certificate, value FSSignatureCallbackCertValid can be returned directly.

Parameters

  [in] | cert_path | A full path of a PFX certificate file (including file name and extension), which will be used for signing. This is passed by user from function FSSignature::startSign:cert_password:digest_algorithm:save_path:client_data:pause:.
  [in] | cert_password | A password string used to open the cert file. If this is an empty string, that means no password is required.This is passed by user from function FSSignature::startSign:cert_password:digest_algorithm:save_path:client_data:pause:.
  [in] | client_data | A user-defined object, which is passed by user from function FSSignature::startSign:cert_password:digest_algorithm:save_path:client_data:pause:.

Returns
  Certificate validity. Please refer to values starting from FSSignatureCallbackCertValid and it should be one of these values.

## ◆ continueCalcDigest:client_data:()

- (FSProgressiveState) continueCalcDigest: |  | (id< FSPauseCallback >) | pause
client_data: |  | (void *) | client_data
| required

A callback function used to continue the custom digest calculation process.

Parameters

  [in] | pause | Pause object which decides if the calculation process needs to be paused. If this is nil, it means not to pause during the calculation process. If this is not nil, please check the returned value of function FSPauseCallback::needPauseNow and decide when to pause the calculation process.
  [in] | client_data | Pointer to a user-defined object, which is passed by user from function FSSignature::startSign:cert_password:digest_algorithm:save_path:client_data:pause: or FSSignature::startVerify:pause:.

Returns
  FSProgressiveFinished means the rendering is finished successfully.
  FSProgressiveToBeContinued means the calculation process is not finished yet and callback function FSSignatureCallback::continueCalcDigest:client_data: would be triggered again to continue the process.
  FSProgressiveError means any error occurs.

## ◆ getDigest:()

- (NSData *) getDigest: |  | (void *) | client_data |
| required

A callback function used to get the digest after the calculation process is finished.

This callback function will be triggered when the calculation process is finished successfully.

Parameters

  [in] | client_data | Pointer to a user-defined object, which is passed by user from function FSSignature::startSign:cert_password:digest_algorithm:save_path:client_data:pause: or FSSignature::startVerify:pause:.

Returns
  The digest string. If there is any error, please return an empty string.

## ◆ isNeedPadData()

- (BOOL) isNeedPadData |  |  |
| required

A callback function used to check whether to return all contents with padding zero or not, when callback function FSSignatureCallback::verifySigState:signed_data:client_data: is called.

Returns
  YES means to return all data in contents steam (including padding zero), while NO means to return contents data without padding zero in stream end.

## ◆ sign:cert_file_stream:cert_password:digest_algorithm:client_data:()

- (NSData *) sign: |  | (NSData *) | digest
cert_file_stream: |  | (id< FSFileStreamCallback >) | cert_file_stream
cert_password: |  | (NSString *) | cert_password
digest_algorithm: |  | (FSSignatureDigestAlgorithm) | digest_algorithm
client_data: |  | (void *) | client_data
| required

A callback function used to do signing and return the signed data.

Host application provides this callback function for custom sign mechanism. This callback function would be triggered during the signature signing process.

Parameters

  [in] | digest | The digest data buffer, for source file buffer to be signed.
  [in] | cert_file_stream | The certificate file stream, which will be used for signing.
  [in] | cert_password | The password string, used to open the cert file. If this is an empty string, that means no password is required.
  [in] | digest_algorithm | The algorithm of message digest for signed data. Please refer to values starting from FSSignatureDigestSHA1 and this would be one of these values.
  [in] | client_data | A user-defined object, which is passed by user from function FSSignature::startSign:cert_password:digest_algorithm:save_path:client_data:pause: or FSSignature::startVerify:pause:.

Returns
  Signed data. If there is any error, please return an empty string.
  The length of returned signed data should be within the default length of signature contents which is 7942 by default or specified by fucntion FSSignature::setDefaultContentsLength: before signing the unsigned signature.

## ◆ sign:cert_path:cert_password:digest_algorithm:client_data:()

- (NSData *) sign: |  | (NSData *) | digest
cert_path: |  | (NSString *) | cert_path
cert_password: |  | (NSString *) | cert_password
digest_algorithm: |  | (FSSignatureDigestAlgorithm) | digest_algorithm
client_data: |  | (void *) | client_data
| required

A callback function used to do signing and return the signed data.

Host application provides this callback function for custom sign mechanism. This callback function would be triggered during the signature signing process.

Parameters

  [in] | digest | The digest data buffer, for source file buffer to be signed.
  [in] | cert_path | The certificate file path, which will be used for signing.
  [in] | cert_password | The password string, used to open the cert file. If this is an empty string, that means no password is required.
  [in] | digest_algorithm | The algorithm of message digest for signed data. Please refer to values starting from FSSignatureDigestSHA1 and this would be one of these values.
  [in] | client_data | Pointer to a user-defined object, which is passed by user from function FSSignature::startSign:cert_password:digest_algorithm:save_path:client_data:pause: or FSSignature::startVerify:pause:.

Returns
  Signed data. If there is any error, please return an empty string.
  The length of returned signed data should be within the default length of signature contents which is 7942 by default or specified by fucntion FSSignature::setDefaultContentsLength: before signing the unsigned signature.

## ◆ startCalcDigest:byte_range_array:signature:client_data:()

- (BOOL) startCalcDigest: |  | (id< FSFileReaderCallback >) | file
byte_range_array: |  | (NSArray< NSNumber * > *) | byte_range_array
signature: |  | (FSSignature *) | signature
client_data: |  | (void *) | client_data
| required

A callback function used to start a custom digest calculation, mainly to initialize the calculation process.

Parameters

  [in] | file | When signing a signature, this represents the source file object to be signed. When verifying a signature field, this represents the source file object to be verified.
  [in] | byte_range_array | A byte range array of the signed document(not the source document). Elements in this array always be in pairs of offset-size values in order of: offset,size,offset,size...
  [in] | signature | A signature object.
  [in] | client_data | Pointer to a user-defined object, which is passed by user from function FSSignature::startSign:cert_password:digest_algorithm:save_path:client_data:pause: or FSSignature::startVerify:pause:.

Returns
  YES means the calculation process is successfully started and then FSSignatureCallback::continueCalcDigest:client_data: will be triggered to continue the calculation process. NO means fail to start a calculation process.

## ◆ verifySigState:signed_data:client_data:()

- (FSSignatureStates) verifySigState: |  | (NSData *) | digest
signed_data: |  | (NSData *) | signed_data
client_data: |  | (void *) | client_data
| required

A callback function used to verify the integrity of a signature and return the verify state.

Host application provides this callback function for custom sign mechanism. This callback function would be triggered during the signature verifying process.
From 7.0, this callback function is only used to verify the intergrity of a signature. Please check the comment about return value for more details.

Parameters

  [in] | digest | The digest data buffer, for source file buffer to be verified.
  [in] | signed_data | The signed data buffer.
  [in] | client_data | Pointer to a user-defined object, which is passed by user from function FSSignature::startSign:cert_password:digest_algorithm:save_path:client_data:pause: or FSSignature::startVerify:pause:.

Returns
  Verify state:
  - Please return FSSignatureStateVerifyNoChange alone to indicate that the document has not been changed within the scope of the signature.
  - Otherwise, please return FSSignatureStateVerifyChange alone or combined with other error state value.