| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
All cryptographic operations in GPGME are performed within a context, which contains the internal state of the operation as well as configuration parameters. By using several contexts you can run several cryptographic operations in parallel, with different configuration.
GpgmeCtx type is a handle for a GPGME context,
which is used to hold the configuration, status and result of
cryptographic operations.
6.1 Creating Contexts Creating new GPGME contexts. 6.2 Destroying Contexts Releasing GPGME contexts. 6.3 Context Attributes Setting properties of a context. 6.4 Key Management Managing keys with GPGME. 6.5 Trust Item Management Managing trust items with GPGME. 6.6 Crypto Operations Using a context for cryptography. 6.7 Run Control Controlling how operations are run.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_data_new creates a new GpgmeCtx
object and returns a handle for it in ctx.
The function returns GPGME_No_Error if the context was
successfully created, GPGME_Invalid_Value if ctx is not a
valid pointer, and GPGME_Out_Of_Core if not enough memory is
available.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_release destroys the context with the handle
ctx and releases all associated resources.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
6.3.1 Protocol Selection Selecting the protocol used by a context. 6.3.2 ASCII Armor Requesting ASCII armored output. 6.3.3 Text Mode Choosing canonical text mode. 6.3.4 Included Certificates Including a number of certificates. 6.3.5 Key Listing Mode Selecting key listing mode. 6.3.6 Passphrase Callback Getting the passphrase from the user. 6.3.7 Progress Meter Callback Being informed about the progress.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_set_protocol sets the protocol used within
the context ctx to proto. All crypto operations will be
performed by the crypto engine configured for that protocol.
See section 3. Protocols and Engines.
Setting the protocol with gpgme_set_protocol does not check if
the crypto engine for that protocol is available and installed
correctly. See section 3.1 Engine Version Check.
The function returns GPGME_No_Error if the protocol could be
set successfully, and GPGME_Invalid_Value if protocol is
not a valid protocol.
gpgme_get_protocol retrieves the protocol currently
use with the context ctx.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_set_armor specifies if the output should be
ASCII armored. By default, output is not ASCII
armored.
ASCII armored output is disabled if yes is zero, and enabled otherwise.
gpgme_get_armor returns 1 if the output is
ASCII armored, and 0 if it is not, or if ctx is
not a valid pointer.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_set_textmode specifies if canonical text mode
should be used. By default, text mode is not used.
Text mode is for example used for the RFC2015 signatures; note that the updated RFC 3156 mandates that the mail user agent does some preparations so that text mode is not needed anymore.
This option is only relevant to the OpenPGP crypto engine, and ignored by all other engines.
Canonical text mode is disabled if yes is zero, and enabled otherwise.
gpgme_get_textmode returns 1 if canonical text
mode is enabled, and 0 if it is not, or if ctx is not a
valid pointer.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_set_include_certs specifies how many
certificates should be included in an S/MIME signed message. By
default, only the sender's certificate is included. The possible
values of nr_of_certs are:
-2
-1
0
1
n
n must be positive.
Values of nr_of_certs smaller than -2 are undefined.
This option is only relevant to the CMS crypto engine, and ignored by all other engines.
gpgme_get_include_certs returns the number of
certificates to include into an S/MIME signed message.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_set_keylist_mode changes the default
behaviour of the key listing functions. The value in mode is a
bitwise-or combination of one or multiple of the following bit values:
GPGME_KEYLIST_MODE_LOCAL
GPGME_KEYLIST_MODE_LOCAL symbol specifies that the local
keyring should be searched for keys in the keylisting operation. This
is the default.
GPGME_KEYLIST_MODE_EXTERN
GPGME_KEYLIST_MODE_EXTERN symbol specifies that an external
source should be should be searched for keys in the keylisting
operation. The type of external source is dependant on the crypto
engine used. For example, it can be a remote keyserver or LDAP
certificate server.
At least one of GPGME_KEYLIST_MODE_LOCAL and
GPGME_KEYLIST_MODE_EXTERN must be specified. For future binary
compatibility, you should get the current mode with
gpgme_get_keylist_mode and modify it by setting or clearing the
appropriate bits, and then using that calulcated value in the
gpgme_set_keylisting_mode operation. This will leave all other
bits in the mode value intact (in particular those that are not used
in the current version of the library).
The function returns GPGME_No_Error if the mode could be set
correctly, and GPGME_Invalid_Value if ctx is not a valid
pointer or mode is not a valid mode.
gpgme_get_keylist_mode returns the current key
listing mode of the context ctx. This value can then be
modified and used in a subsequent gpgme_set_keylist_mode
operation to only affect the desired bits (and leave all others
intact).
The function returns 0 if ctx is not a valid pointer, and the current mode otherwise. Note that 0 is not a valid mode value.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GpgmePassphraseCb type is the type of functions usable as
passphrase callback function.
The string desc contains a text usable to be displayed to the
user of the application. The function should return a passphrase for
the context when invoked with desc not being NULL.
The user may store information about the resources associated with the returned passphrase in *r_hd. When the passphrase is no longer needed by GPGME, the passphrase callback function will be called with desc being NULL, and r_hd being the same as at the first invocation.
gpgme_set_passphrase_cb sets the function that is
used when a passphrase needs to be provided by the user to
passfunc. The function passfunc needs to implemented by
the user, and whenever it is called, it is called with its first
argument being hook_value. By default, no passphrase callback
function is set.
Not all crypto engines require this callback to retrieve the passphrase. It is better if the engine retrieves the passphrase from a trusted agent (a daemon process), rather than having each user to implement their own passphrase query.
The user can disable the use of a passphrase callback function by
calling gpgme_set_passphrase_cb w
2000
ith passfunc being
NULL.
gpgme_get_passphrase_cb returns the function that
is used when a passphrase needs to be provided by the user in
*passfunc, and the first argument for this function in
*hook_value. If no passphrase callback is set, or ctx is
not a valid pointer, NULL is returned in both variables.
passfunc or hook_value can be NULL. In this case,
the corresponding value will not be returned.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GpgmeProgressCb type is the type of functions usable as
progress callback function.
The arguments are specific to the crypto engine. More information about the progress information returned from the GnuPG engine can be found in the GnuPG source code in the file `doc/DETAILS' in the section PROGRESS.
gpgme_set_progress_cb sets the function that is
used when progress information about a cryptographic operation is
available. The function progfunc needs to implemented by the
user, and whenever it is called, it is called with its first argument
being hook_value. By default, no progress callback function
is set.
Setting a callback function allows an interactive program to display progress information about a long operation to the user.
The user can disable the use of a progress callback function by
calling gpgme_set_progress_cb with progfunc being
NULL.
gpgme_get_progress_cb returns the function that is
used to inform the user about the progress made in *progfunc,
and the first argument for this function in *hook_value. If no
progress callback is set, or ctx is not a valid pointer,
NULL is returned in both variables.
progfunc or hook_value can be NULL. In this case,
the corresponding value will not be returned.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Some of the cryptographic operations require that recipients or signers are specified. This is always done by specifying the respective keys that should be used for the operation. The following section describes how such keys can be selected and manipulated.
GpgmeKey type is a handle for a public or secret key, and
is used to select the key for operations involving it.
A key can contain several user IDs and sub keys.
6.4.1 Listing Keys Browsing the list of available keys. 6.4.2 Information About Keys Requesting detailed information about keys. 6.4.3 Manipulating Keys Operations on keys. 6.4.4 Generating Keys Creating new key pairs. 6.4.5 Exporting Keys Retrieving key data from the key ring. 6.4.6 Importing Keys Adding keys to the key ring. 6.4.7 Deleting Keys Removing keys from the key ring.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_op_keylist_start initiates a key listing
operation inside the context ctx. It sets everything up so that
subsequent invocations of gpgme_op_keylist_next return the keys
in the list.
If pattern is NULL, all available keys are returned.
Otherwise, pattern contains an engine specific expression that
is used to limit the list to all keys matching the pattern.
If secret_only is not 0, the list is restricted to secret
keys only.
The context will be busy until either all keys are received (and
gpgme_op_keylist_next returns GPGME_EOF), or
gpgme_op_keylist_end is called to finish the operation.
The function returns GPGME_Invalid_Value if ctx is not a
valid pointer, and passes through any errors that are reported by the
crypto engine support routines.
gpgme_op_keylist_ext_start initiates an extended
key listing operation inside the context ctx. It sets
everything up so that subsequent invocations of
gpgme_op_keylist_next return the keys in the list.
If pattern or *pattern is NULL, all available keys
are returned. Otherwise, pattern is a NULL terminated
array of strings that are used to limit the list to all keys matching
at least one of the patterns verbatim.
If secret_only is not 0, the list is restricted to secret
keys only.
The value of reserved must be 0.
The context will be busy until either all keys are received (and
gpgme_op_keylist_next returns GPGME_EOF), or
gpgme_op_keylist_end is called to finish the operation.
The function returns GPGME_Invalid_Value if ctx is not a
valid pointer, and passes through any errors that are reported by the
crypto engine support routines.
gpgme_op_keylist_next returns the next key in the
list created by a previous gpgme_op_keylist_start operation in
the context ctx. The key will have one reference for the user.
See section 6.4.3 Manipulating Keys.
This is the only way to get at GpgmeKey objects in
GPGME.
If the last key in the list has already been returned,
gpgme_op_keylist_next returns GPGME_EOF.
The function returns GPGME_Invalid_Value if ctx or
r_key is not a valid pointer, GPGME_No_Request if there
is no pending operation, GPGME_Out_Of_Core if there is not
enough memory for the operation.
gpgme_op_keylist_next ends a pending key list
operation in the context ctx.
The function returns GPGME_Invalid_Value if ctx is not a
valid pointer, GPGME_No_Request if there is no pending
operation, GPGME_Out_Of_Core if at some time during the
operation there was not enough memory available.
The following example illustrates how all keys containing a certain
string (g10code) can be listed with their key ID and the name
and e-mail address of the main user ID:
GpgmeCtx ctx;
GpgmeError err = gpgme_new (&ctx);
if (!err)
{
err = gpgme_op_keylist_start (ctx, "g10code", 0);
while (!err && (err = gpgme_op_keylist_next (ctx, &key)) != GPGME_EOF)
{
printf ("%s: %s <%s>\n",
gpgme_key_get_string_attr (key, GPGME_ATTR_KEYID, 0, 0),
gpgme_key_get_string_attr (key, GPGME_ATTR_NAME, 0, 0),
gpgme_key_get_string_attr (key, GPGME_ATTR_EMAIL, 0, 0));
gpgme_key_release (key);
}
gpgme_release (ctx);
}
if (err)
{
fprintf (stderr, "%s: can not list keys: %s\n",
argv[0], gpgme_strerror (err));
exit (1);
}
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_key_get_as_xml returns a string in
XML format describing the key key. The user has to
release the string with free.
The function returns NULL if key is not a valid pointer,
or there is not enough memory available.
GpgmeAttr type is used to specify a key or trust item
attribute. The following attributes are defined:
GPGME_ATTR_KEYID
For trust items, the trust item refers to the key with this ID.
GPGME_ATTR_FPR
GPGME_ATTR_ALGO
enum gcry_pk_algos values in the gcrypt library.
GPGME_ATTR_LEN
GPGME_ATTR_CREATED
GPGME_ATTR_EXPIRE
GPGME_ATTR_OTRUST
GPGME_ATTR_USERID
For trust items, this is the user ID associated with this trust item.
GPGME_ATTR_NAME
GPGME_AT
2000
TR_EMAIL
GPGME_ATTR_COMMENT
GPGME_ATTR_VALIDITY
For trust items, this is the validity that is associated with this trust item.
GPGME_ATTR_UID_REVOKED
1 if the user ID is revoked, and 0
otherwise.
GPGME_ATTR_UID_INVALID
1 if the user ID is invalid, and 0
otherwise.
GPGME_ATTR_LEVEL
GPGME_ATTR_TYPE
GPGME_ATTR_IS_SECRET
1, otherwise it is NULL or 0.
GPGME_ATTR_KEY_REVOKED
1 if the key is revoked, and 0 otherwise.
GPGME_ATTR_KEY_INVALID
1 if the key is invalid, and 0 otherwise.
GPGME_ATTR_KEY_EXPIRED
1 if the key is expired, and 0 otherwise.
GPGME_ATTR_KEY_DISABLED
1 if the key is disabled, and 0 otherwise.
GPGME_ATTR_KEY_CAPS
GPGME_ATTR_CAN_ENCRYPT
1 if the sub key can be used
for encryption, and 0 otherwise.
GPGME_ATTR_CAN_SIGN
1 if the sub key can be used
for signatures, and 0 otherwise.
GPGME_ATTR_CAN_CERTIFY
1 if the sub key can be used
for certifications, and 0 otherwise.
GPGME_ATTR_SERIAL
GPGME_ATTR_ISSUE
GPGME_ATTR_CHAINID
GpgmeValidity type is used to specify the validity of a user ID
in a key. The following validities are defined:
GPGME_VALIDITY_UNKNOWN
GPGME_VALIDITY_UNDEFINED
GPGME_VALIDITY_NEVER
GPGME_VALIDITY_MARGINAL
GPGME_VALIDITY_FULL
GPGME_VALIDITY_ULTIMATE
gpgme_key_get_string_attr returns the value of the
string-representable attribute what of key key. If the
attribute is an attribute of a sub key or an user ID, idx
specifies the sub key or user ID of which the attribute value is
returned. The argument reserved is reserved for later use and
should be NULL.
The string returned is only valid as long as the key is valid.
The function returns 0 if an attribute can't be returned as a
string, key is not a valid pointer, idx out of range,
or reserved not NULL.
gpgme_key_get_ulong_attr returns the value of the
number-representable attribute what of key key. If the
attribute is an attribute of a sub key or an user ID, idx
specifies the sub key or user ID of which the attribute value is
returned. The argument reserved is reserved for later use and
should be NULL.
The function returns 0 if the attribute can't be returned as a
number, key is not a valid pointer, idx out of range,
or reserved not NULL.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_key_ref acquires an additional reference for
the key key.
gpgme_key_ref releases a reference for the key
key. If this was the last reference, the k
2000
ey will be destroyed
and all resources associated to it will be released.
The function gpgme_key_release is an alias for
gpgme_key_unref.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_op_genkey generates a new key pair in the
context ctx and puts it into the standard key ring if both
pubkey and seckey are NULL. In this case the
function returns immediately after starting the operation, and does
not wait for it to complete. If pubkey is not NULL it
should be the handle for an empty (newly created) data object, and
upon successful completion the data object will contain the public
key. If seckey is not NULL it should be the handle for
an empty (newly created) data object, and upon successful completion
the data object will contain the secret key.
Note that not all crypto engines support this interface equally.
GnuPG does not support pubkey and subkey, they should be
both NULL, and the key pair will be added to the standard key
ring. GpgSM does only support pubkey, the secret key will be
stored by gpg-agent. GpgSM expects pubkey being not
NULL.
The argument parms specifies parameters for the key in an XML string. The details about the format of parms are specific to the crypto engine used by ctx. Here is an example for GnuPG as the crypto engine:
<GnupgKeyParms format="internal"> Key-Type: DSA Key-Length: 1024 Subkey-Type: ELG-E Subkey-Length: 1024 Name-Real: Joe Tester Name-Comment: with stupid passphrase Name-Email: joe@foo.bar Expire-Date: 0 Passphrase: abc </GnupgKeyParms> |
Here is an example for GpgSM as the crypto engine:
<GnupgKeyParms format="internal"> Key-Type: RSA Key-Length: 1024 Name-DN: C=de,O=g10 code,OU=Testlab,CN=Joe 2 Tester Name-Email: joe@foo.bar </GnupgKeyParms> |
Strings should be given in UTF-8 encoding. The only format supported
for now is "internal". The content of the GnupgKeyParms
container is passed verbatim to GnuPG. Control statements are not
allowed.
The function returns GPGME_No_Error if the operation could be
started successfully, GPGME_Invalid_Value if parms is not
a valid XML string, GPGME_Not_Supported if pubkey or
seckey is not valid, and GPGME_General_Error if no key
was created by the backend.
gpgme_op_genkey_start initiates a
gpgme_op_genkey operation. It can be completed by calling
gpgme_wait on the context. See section 6.7.1 Waiting For Completion.
The function returns GPGME_No_Error if the operation could be
started successfully, GPGME_Invalid_Value if parms is not
a valid XML string, and GPGME_Not_Supported if pubkey or
seckey is not NULL.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_op_export extracts the public keys of the
user IDs in recipients and returns them in the data buffer
keydata. The type of the public keys returned is determined by
the ASCII armor attribute set for the context ctx.
The function returns GPGME_No_Error if the operation completed
successfully, GPGME_Invalid_Value if recipients is
NULL or keydata is not a valid empty data buffer, and
passes through any errors that are reported by the crypto engine
support routines.
gpgme_op_export_start initiates a
gpgme_op_export operation. It can be completed by calling
gpgme_wait on the context. See section 6.7.1 Waiting For Completion.
The function returns GPGME_No_Error if the operation could be
started successfully, and GPGME_Invalid_Value if
recipients is NULL or keydata is not a valid empty
data buffer.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_op_import adds the keys in the data buffer
keydata to the key ring of the crypto engine used by ctx.
The format of keydata can be ASCII armored, for example,
but the details are specific to the crypto engine.
More information about the import is available with
gpgme_get_op_info. See section 6.6.6 Detailed Results.
The function returns GPGME_No_Error if the import was completed
successfully, GPGME_Invalid_Value if keydata if ctx
or keydata is not a valid pointer, and GPGME_No_Data if
keydata is an empty data buffer.
gpgme_op_import_start initiates a
gpgme_op_import operation. It can be completed by calling
gpgme_wait on the context. See section 6.7.1 Waiting For Completion.
The function returns GPGME_No_Error if the import could be
started successfully, GPGME_Invalid_Value if keydata if
ctx or keydata is not a valid pointer, and
GPGME_No_Data if keydata is an empty data buffer.
gpgme_op_import_ext is like
gpgme_op_import, but also returns the number of processed keys
in nr. This is the same as the count information in the
detailed results available with gpgme_get_op_info.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_op_delete deletes the key key from the
key ring of the crypto engine used by ctx. If
allow_secret is 0, only public keys are deleted,
otherwise secret keys are deleted as well, if that is supported.
The function returns GPGME_No_Error if the key was deleted
successfully, GPGME_Invalid_Value if ctx or key is
not a valid pointer, GPGME_Invalid_Key if key could not
be found in the keyring, and GPGME_Conflict if the secret key
for key is available, but allow_secret is zero.
gpgme_op_delete_start initiates a
gpgme_op_delete operation. It can be completed by calling
gpgme_wait on the context. See section 6.7.1 Waiting For Completion.
The function returns GPGME_No_Error if the operation was
started successfully, and GPGME_Invalid_Value if ctx or
key is not a valid pointer.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Caution: The trust items interface is experimental.
GpgmeTrustItem type is a handle for a trust item.
6.5.1 Listing Trust Items Browsing the list of available trust items. 6.5.2 Information About Trust Items Requesting detailed information about trust items. 6.5.3 Manipulating Trust Items Operations on trust items.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_op_trustlist_start initiates a trust item
listing operation inside the context ctx. It sets everything up
so that subsequent invocations of gpgme_op_trustlist_next return
the trust items in the list.
The string pattern contains an engine specific expression that is used to limit the list to all trust items matching the pattern. It can not be the empty string.
The argument max_level is currently ignored.
The context will be busy until either all trust items are received
(and gpgme_op_trustlist_next returns GPGME_EOF), or
gpgme_op_trustlist_end is called to finish the operation.
The function returns GPGME_Invalid_Value if ctx is not a
valid pointer, and passes through any errors that are reported by the
crypto engine support routines.
gpgme_op_trustlist_next returns the next trust
item in the list created by a previous gpgme_op_trustlist_start
operation in the context ctx. The trust item can be destroyed
with gpgme_trust_item_release. See section 6.5.3 Manipulating Trust Items.
This is the only way to get at GpgmeTrustItem objects in
GPGME.
If the last trust item in the list has already been returned,
gpgme_op_trustlist_next returns GPGME_EOF.
The function returns GPGME_Invalid_Value if ctx or
r_item is not a valid pointer, GPGME_No_Request if there
is no pending operation, GPGME_Out_Of_Core if there is not
enough memory for the operation.
gpgme_op_trustlist_next ends a pending key list
operation in the context ctx.
The function returns GPGME_Invalid_Value if ctx is not a
valid pointer, GPGME_No_Request if there is no pending
operation, GPGME_Out_Of_Core if at some time during the
operation there was not enough memory available.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Trust items have attributes which can be queried using the interfaces below. The attribute identifiers are shared with those for key attributes. See section 6.4.2 Information About Keys.
gpgme_trust_item_get_string_attr returns the value
of the string-representable attribute what of trust item
item. The arguments idx and reserved are reserved
for later use and should be 0 and NULL respectively.
The string returned is only valid as long as the key is valid.
The function returns 0 if an attribute can't be returned as a
string, key is not a valid pointer, idx out of range,
or reserved not NULL.
gpgme_trust_item_get_int_attr returns the value of
the number-representable attribute what of trust item
item. If the attribute occurs more than once in the trust item,
the index is specified by idx. However, currently no such
attribute exists, so idx should be 0. The argument
reserved is reserved for later use and should be NULL.
The function returns 0 if the attribute can't be returned as a
number, key is not a valid pointer, idx out of range,
or reserved not NULL.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_trust_item_release destroys a
GpgmeTrustItem object and releases all associated resources.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top 2000 ] | [Contents] | [Index] | [ ? ] |
6.6.1 Decrypt Decrypting a ciphertext. 6.6.2 Verify Verifying a signature. 6.6.3 Decrypt and Verify Decrypting a signed ciphertext. 6.6.4 Sign Creating a signature. 6.6.5 Encrypt Encrypting a plaintext. 6.6.6 Detailed Results How to obtain more info about the operation.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_op_decrypt decrypts the ciphertext in the
data object cipher and stores it into the data object
plain.
The function returns GPGME_No_Error if the ciphertext could be
decrypted successfully, GPGME_Invalid_Value if ctx,
cipher or plain is not a valid pointer,
GPGME_No_Data if cipher does not contain any data to
decrypt, GPGME_Decryption_Failed if cipher is not a valid
cipher text, GPGME_No_Passphrase if the passphrase for the
secret key could not be retrieved, and passes through any errors that
are reported by the crypto engine support routines.
gpgme_op_decrypt_start initiates a
gpgme_op_decrypt operation. It can be completed by calling
gpgme_wait on the context. See section 6.7.1 Waiting For Completion.
The function returns GPGME_No_Error if the operation could be
started successfully, and GPGME_Invalid_Value if cipher
or plain is not a valid pointer.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GpgmeSigStat type holds the result of a signature check, or
the combined result of all signatures. The following results are
possible:
GPGME_SIG_STAT_NONE
GPGME_SIG_STAT_GOOD
GPGME_SIG_STAT_GOOD_EXP
GPGME_SIG_STAT_GOOD_EXPKEY
GPGME_SIG_STAT_BAD
GPGME_SIG_STAT_NOKEY
GPGME_SIG_STAT_NOSIG
GPGME_SIG_STAT_ERROR
GPGME_SIG_STAT_DIFF
gpgme_get_sig_status.
gpgme_op_verify verifies that the signature in the
data object sig is a valid signature. If plain is
initialized with plaintext data, it is assumed that sig is a
detached signature, and its validity for the plaintext given in
plain is verified. If plain is an uninitialized data
object, it is assumed that sig is a normal (or cleartext)
signature, and the plaintext is available in plain after
successful verification.
The combined status of all signatures is returned in r_stat.
The results of the individual signature verifications can be retrieved
with gpgme_get_sig_status and gpgme_get_sig_key.
The function returns GPGME_No_Error i
2000
f the operation could be
completed successfully, GPGME_Invalid_Value if ctx,
sig, plain or r_stat is not a valid pointer,
GPGME_No_Data if sig does not contain any data to verify,
and passes through any errors that are reported by the crypto engine
support routines.
gpgme_op_verify_start initiates a
gpgme_op_verify operation. It can be completed by calling
gpgme_wait on the context. See section 6.7.1 Waiting For Completion.
The function returns GPGME_No_Error if the operation could be
started successfully, GPGME_Invalid_Value if ctx,
sig, plain or r_stat is not a valid pointer, and
GPGME_No_Data if sig or plain does not contain any
data to verify.
gpgme_get_sig_status receives information about a
signature after the gpgme_op_verify or
gpgme_op_verify_decrypt operation. A single detached signature
can contain signatures by more than one key. The idx specifies
which signature's information should be retrieved, starting from
0.
The status of the signature will be returned in r_stat if it is
not NULL. The creation time stamp of the signature will be
returned in r_created if it is not NULL.
The function returns a statically allocated string that contains the
fingerprint of the key which signed the plaintext, or NULL if
ctx is not a valid pointer, the operation is still pending, or
no verification could be performed.
gpgme_get_sig_status but may be used
to retrieve more detailed information. ctx should be the context
used for the last signature verification, idx is used to enumerate
over all signatures starting with 0 and whatidx should be
0 unless otherwise stated.
The following values may be used for what:
GPGME_ATTR_FPR
GPGME_ATTR_ERRTOK
0 returns an error token associated with validity calculation,
a value of 1 return an error token related to the certificate
checking.
gpgme_get_sig_string_attr but used
for attributes which can be represented by an unsigned long data
type. ctx should be the context used for the last signature
verification, idx is used to enumerate over all signatures
starting with 0 and whatidx should be 0 unless
otherwise stated.
The following values may be used for what:
GPGME_ATTR_CREATED
gpgme_get_sig_status.
GPGME_ATTR_EXPIRE
GPGME_ATTR_VALIDITY
GPGME_VALIDITY_UNKNOWN, GPGME_VALIDITY_NEVER,
GPGME_VALIDITY_MARGINAL or GPGME_VALIDITY_FULL.
GPGME_ATTR_SIG_STATUS
gpgme_get_sig_status.
GPGME_ATTR_SIG_SUMMARY
The defined bits are:
GPGME_SIGSUM_VALID
GPGME_SIGSUM_GREEN
GPGME_SIGSUM_RED
GPGME_SIGSUM_KEY_REVOKED
GPGME_SIGSUM_KEY_EXPIRED
GPGME_SIGSUM_SIG_EXPIRED
GPGME_SIGSUM_KEY_MISSING
GPGME_SIGSUM_CRL_MISSING
GPGME_SIGSUM_CRL_TOO_OLD
GPGME_SIGSUM_BAD_POLICY
GPGME_SIGSUM_SYS_ERROR
gpgme_get_sig_status receives a GpgmeKey
object for the key which was used to verify the signature after the
gpgme_op_verify or gpgme_op_verify_decrypt operation. A
single detached signature can contain signatures by more than one key.
The idx specifies which signature's information should be
retrieved, starting from 0. The key will have on reference for
the user.
The function is a convenient way to retrieve the keys belonging to the
fingerprints returned by gpgme_get_sig_status.
The function returns GPGME_No_Error if the key could be
returned, GPGME_Invalid_Value if r_key is not a valid
pointer, GPGME_Invalid_Key if the fingerprint is not valid,
GPGME_EOF if idx is too large, or some other error value
if a problem occurred requesting the key.
gpgme_get_notation can be used to retrieve
notation data from the last signature check in the context ctx.
If there is notation data available from the last signature check,
this function may be used to return this notation data as a string.
The string is an XML representation of that data embedded in a
<notation> container. The user has to release the string with
free.
The function returns a string if the notation data is available or
NULL if there is no such data available.
< 2000 A NAME="Decrypt and Verify">
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_op_decrypt_verify decrypts the ciphertext in
the data object cipher and stores it into the data object
plain. If cipher contains signatures, they will be
verified and their combined status will be returned in r_stat.
After the operation completed, gpgme_op_get_sig_status and
gpgme_op_get_sig_key can be used to retrieve more information
about the signatures.
The function returns GPGME_No_Error if the ciphertext could be
decrypted successfully, GPGME_Invalid_Value if ctx,
cipher, plain or r_stat is not a valid pointer,
GPGME_No_Data if cipher does not contain any data to
decrypt, GPGME_Decryption_Failed if cipher is not a valid
cipher text, GPGME_No_Passphrase if the passphrase for the
secret key could not be retrieved, and passes through any errors that
are reported by the crypto engine support routines.
gpgme_op_decrypt_verify_start initiates a
gpgme_op_decrypt_verify operation. It can be completed by
calling gpgme_wait on the context. See section 6.7.1 Waiting For Completion.
The function returns GPGME_No_Error if the operation could be
started successfully, GPGME_Invalid_Value if ctx,
cipher, plain or r_stat is not a valid pointer, and
GPGME_No_Data if cipher does not contain any data to
decrypt.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A signature can contain signatures by one or more keys. The set of keys used to create a signatures is contained in a context, and is applied to all following signing operations in this context (until the set is changed).
6.6.4.1 Selecting Signers How to choose the keys to sign with. 6.6.4.2 Creating a Signature How to create a signature.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_signers_clear releases a reference for each
key on the signers list and removes the list of signers from the
context ctx.
Every context starts with an empty list.
gpgme_signers_add adds the key key to the
list of signers in the context ctx.
Calling this function acquires an additional reference for the key.
gpgme_signers_enum returns the seqth key in
the list of signers in the context ctx. An additional reference
is acquired for the user.
If seq is out of range, NULL is returned.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GpgmeSigMode type is used to specify the desired type of a
signature. The following modes are available:
GPGME_SIG_MODE_NORMAL
GPGME_SIG_MODE_DETACH
GPGME_SIG_MODE_CLEAR
gpgme_op_sign creates a signature for the text in
the data object plain and returns it in the data object
sig. The type of the signature created is determined by the
ASCII armor and text mode attributes set for the context
ctx and the requested signature mode mode.
More information about the signatures is available with
gpgme_get_op_info. See section 6.6.6 Detailed Results.
If an S/MIME signed message is created using the CMS crypto engine,
the number of certificates to include in the message can be specified
with gpgme_set_include_certs. See section 6.3.4 Included Certificates.
The function returns GPGME_No_Error if the signature could be
created successfully, GPGME_Invalid_Value if ctx,
plain or sig is not a valid pointer, GPGME_No_Data
if the signature could not be created, GPGME_No_Passphrase if
the passphrase for the secret key could not be retrieved, and passes
through any errors that are reported by the crypto engine support
routines.
gpgme_op_sign_start initiates a
gpgme_op_sign operation. It can be completed by calling
gpgme_wait on the context. See section 6.7.1 Waiting For Completion.
The function returns GPGME_No_Error if the operation could be
started successfully, and GPGME_Invalid_Value if ctx,
plain or sig is not a valid pointer.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
One plaintext can be encrypted for several recipients at the same time. The list of recipients is created independently of any context, and then passed to the encryption operation.
6.6.5.1 Selecting Recipients How to choose the recipients. 6.6.5.2 Encrypting a Plaintext How to encrypt a plaintext.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GpgmeRecipients type is a handle for a set of recipients
that can be used in an encryption process.
gpgme_recipients_new creates a new, empty set of
recipients and returns a handle for it in r_rset.
The function returns GPGME_No_Error if the recipient set could
be created successfully, and GPGME_Out_Of_Core if not enough
memory was available.
gpgme_recipients_release destroys the set of
recipients rset and releases all associated resources.
gpgme_recipients_add_name adds the recipient
name to the set of recipients rset. This is equivalent to
gpgme_recipients_add_name_with_validity with a validity of
GPGME_VALIDITY_UNKNOWN.
The function returns GPGME_No_Error if the recipient was added
successfully, GPGME_Invalid_Value if rset or name
is not a valid pointer, and GPGME_Out_Of_Core if not enough
memory is available.
gpgme_recipients_add_name_with_validity adds the
recipient name with the validity val to the set of
recipients rset. If the validity is not known, the function
gpgme_recipients_add_name can be used.
See section 6.4.2 Information About Keys, for the possible values for val.
The function returns GPGME_No_Error if the recipient was added
successfully, GPGME_Invalid_Value if rset or name
is not a valid pointer, and GPGME_Out_Of_Core if not enough
memory is available.
gpgme_recipients_count returns the number of
recipients in the set rset.
gpgme_recipients_enum_open creates a new iterator
iter that can be used to walk through the set of recipients in
rset, using gpgme_recipients_enum_read.
If the iterator is not needed anymore, it can be closed with
gpgme_recipients_enum_close.
The function returns GPGME_No_Error if the enumerator was
successfully created and GPGME_Invalid_Value if rset or
iter is not a valid pointer.
gpgme_recipients_enum_read returns a string
containing the name of the next recipient in the set rset for
the iterator iter. The string is valid as long as rset is
valid or the function is called the next time with the same recipient
set and iterator, whatever is earlier.
gpgme_recipients_enum_close releases the iterator
iter for the recipient set rset.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_op_encrypt encrypts the plaintext in the data
object plain for the recipients rset and stores the
ciphertext in the data object cipher. The type of the
ciphertext created is determined by the ASCII armor and text
mode attributes set for the context ctx.
If GPGME_Invalid_Recipients is returned, some recipients in
rset are invalid, but not all. In this case the plaintext is
encrypted for all valid recipients and returned in cipher. More
information about the invalid recipients is available with
gpgme_get_op_info. See section 6.6.6 Detailed Results.
If recp is NULL, symmetric rather than public key
encryption is performed. Symmetrically encrypted cipher text can be
deciphered with gpgme_op_decrypt. Note that in this case the
crypto backend needs to retrieve a passphrase from the user.
Symmetric encryption is currently only supported for the OpenPGP
crypto backend.
The function returns GPGME_No_Error if the ciphertext could be
created successfully, GPGME_Invalid_Value if ctx,
rset, plain or cipher is not a valid pointer,
GPGME_No_Recipients if rset does not contain any valid
recipients, GPGME_Invalid_Recipients if rset contains
some invalid recipients, GPGME_No_Passphrase if the passphrase
for the secret key could not be retrieved, and passes through any
errors that are reported by the crypto engine support routines.
gpgme_op_encrypt_start initiates a
gpgme_op_encrypt operation. It can be completed by calling
gpgme_wait on the context. See section 6.7.1 Waiting For Completion.
The function returns GPGME_No_Error if the operation could be
started successfully, GPGME_Invalid_Value if ctx,
rset, plain or cipher is not a valid pointer, and
GPGME_No_Recipients if rset does not contain any valid
recipients.
gpgme_op_encrypt_sign does a combined encrypt and
sign operation. It is used like gpgme_op_encrypt, but the
ciphertext also contains signatures for the signers listed in
ctx.
The combined encrypt and sign operation is currently only available for the OpenPGP crypto engine.
gpgme_op_encrypt_sign_start initiates a
gpgme_op_encrypt_sign operation. It can be completed by
calling gpgme_wait on the context. See section 6.7.1 Waiting For Completion.
The function returns GPGME_No_Error if the operation could be
started successfully, GPGME_Invalid_Value if ctx,
rset, plain or cipher is not a valid pointer, and
GPGME_No_Recipients if rset does not contain any valid
recipients.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_get_op_info retrieves more information about
the last crypto operation.
The function returns a string in the XML format. The user has to
release the string with free.
Here is a sample of the information that might be returned:
<GnupgOperationInfo>
<signature>
<detached/> <!-- or cleartext or standard -->
<algo>17</algo>
<hashalgo>2</hashalgo>
<micalg>pgp-sha1</micalg>
<sigclass>01</sigclass>
<created>9222222</created>
<fpr>121212121212121212</fpr>
</signature>
</GnupgOperationInfo>
|
Currently, the only operations that return additional information are encrypt, sign and import. See section 6.6.5 Encrypt, See section 6.6.4 Sign, See section 6.4.6 Importing Keys.
The function returns a string or NULL if no such data is
available.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GPGME supports running operations synchronously and asynchronously. You can use asynchronous operation to set up a context up to initiating the desired operation, but delay performing it to a later point.
Furthermore, you can use an external event loop to control exactly when GPGME runs. This ensures that GPGME only runs when necessary and also prevents it from blocking for a long time.
6.7.1 Waiting For Completion Waiting until an operation is completed. 6.7.2 Cancelling an Operation Interrupting a running operation. 6.7.3 Hooking Up Into Idle Time Doing something when nothing has to be done. 6.7.4 Using External Event Loops Advanced control over what happens when.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_wait continues the pending operation within
the context ctx. In particular, it ensures the data exchange
between GPGME and the crypto backend and watches over the
run time status of the backend process.
If hang is true, the function does not return until the operation is completed or cancelled. Otherwise the function will not block for a long time.
The error status of the finished operation is returned in status
if gpgme_wait does not return NULL.
The ctx argument can be NULL. In that case,
gpgme_wait waits for any context to complete its operation.
gpgme_wait can be used only in conjunction with any context
that has a pending operation initiated with one of the
gpgme_op_*_start functions except gpgme_op_keylist_start
and gpgme_op_trustlist_start (for which you should use the
corresponding gpgme_op_*_next functions). If ctx is
NULL, all of such contexts are waited upon and possibly
returned. Synchronous operations running in parallel, as well as key
and trust item list operations, do not affect gpgme_wait.
In a multi-threaded environment, only one thread should ever call
gpgme_wait at any time, irregardless if ctx is specified
or not. This means that all calls to this function should be fully
synchronized by locking primitives.
The function returns the ctx of the context which has finished the operation.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_cancel tries to cancel the pending
operation. A running synchronous operation in the context or the
function gpgme_wait with this context as its ctx argument
might notice the cancellation flag and return. It is currently not
guaranteed to work under all circumstances. Its current primary
purpose is to prevent asking for a passphrase again in the passphrase
callback.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GpgmeIdleFunc type is the type of functions usable as
an idle function that can be registered with gpgme_register_idle.
gpgme_register_idle can be used to register
idle as the idle function.
idle will be called whenever GPGME thinks that it is
idle and time can better be spent elsewhere. Setting idle to
NULL disables use of the idle function (this is the default).
The function returns the old idle function, or NULL if none was
registered yet.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GPGME hides the complexity of the communication between the
library and the crypto engine. The price of this convenience is that
the calling thread can block arbitrary long waiting for the data
returned by the crypto engine. In single-threaded programs, in
particular if they are interactive, this is an unwanted side-effect.
OTOH, if gpgme_wait is used without the hang option being
enabled, it might be called unnecessarily often, wasting CPU time that
could be used otherwise.
The I/O callback interface described in this section lets the user take control over what happens when. GPGME will provide the user with the file descriptors that should be monitored, and the callback functions that should be invoked when a file descriptor is ready for reading or writing. It is then the user's responsibility to decide when to check the file descriptors and when to invoke the callback functions. Usually this is done in an event loop, that also checks for events in other parts of the program. If the callback functions are only called when the file descriptors are ready, GPGME will never block. This gives the user mroe control over the program flow, and allows to perform other tasks when GPGME would block otherwise.
By using this advanced mechanism, GPGME can be integrated smoothly into GUI toolkits like GTK+ even for single-threaded programs.
6.7.4.1 I/O Callback Interface How I/O callbacks are registered. 6.7.4.2 Registering I/O Callbacks How to use I/O callbacks for a context. 6.7.4.3 I/O Callback Example An example how to use I/O callbacks. 6.7.4.4 I/O Callback Example GTK+ How to use GPGME with GTK+. 6.7.4.5 I/O Callback Example GDK How to use GPGME with GDK.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GpgmeIOCb type is the type of functions which
GPGME wants to register as I/O callback handlers using the
GpgmeRegisterIOCb functions provided by the user.
data and fd are provided by GPGME when the I/O callback handler is registered, and should be passed through to the handler when it is invoked by the user because it noticed activity on the file descriptor fd.
GpgmeRegisterIOCb type is the type of functions which can
be called by GPGME to register an I/O callback funtion
fnc for the file descriptor fd with the user.
fnc_data should be passed as the first argument to fnc
when the handler is invoked (the second argument should be fd).
If dir is 0, fnc should be called by the user when
fd is ready for writing. If dir is 1, fnc should be
called when fd is ready for reading.
data was provided by the user when registering the
GpgmeRegisterIOCb function with GPGME and will always
be passed as the first argument when registering a callback function.
For example, the user can use this to determine the event loop to
which the file descriptor should be added.
GPGME will call this function when a crypto operation is
initiated in a context for which the user has registered I/O callback
handler functions with gpgme_set_io_cbs. It can also call this
function when it is in an I/O callback handler for a file descriptor
associated to this context.
The user should return a unique handle in tag identifying this
I/O callback registration, which will be passed to the
GpgmeRegisterIOCb function without interpretation when the file
descriptor should not be monitored anymore.
GpgmeRemoveIOCb type is the type of functions which can be
called by GPGME to remove an I/O callback handler that was
registered before. tag is the handle that was returned by the
GpgmeRegisterIOCb for this I/O callback.
GPGME can call this function when a crypto operation is in an I/O callback. It will also call this function when the context is destroyed while an operation is pending.
GpgmeEventIO type specifies the type of an event that is
reported to the user by GPGME as a consequence of an I/O
operation. The following events are defined:
GPGME_EVENT_DONE
GpgmeError variable that contains the status of the operation
that finished. This event is signalled after the last I/O callback
has been removed.
GPGME_EVENT_NEXT_KEY
gpgme_op_keylist_start operation, the next key was
received from the crypto engine. The accompanying type_data is
a GpgmeKey variable that contains the key with one reference
for the user.
GPGME_EVENT_NEXT_TRUSTITEM
gpgme_op_trustlist_start operation, the next trust item
was received from the crypto engine. The accompanying type_data
is a GpgmeTrustItem variable that contains the trust item with
one reference for the user.
GpgmeEventIOCb type is the type of functions which can be
called by GPGME to signal an event for an operation running
in a context which has I/O callback functions registered by the user.
data was provided by the user when registering the
GpgmeEventIOCb function with GPGME and will always be
passed as the first argument when registering a callback function.
For example, the user can use this to determine the context in which
this event has occured.
type will specify the type of event that has occured.
type_data specifies the event further, as described in the above
list of possible GpgmeEventIO types.
GPGME can call this function in an I/O callback handler.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GpgmeRegisterIOCb add
void *add_data
add function when
it is called by GPGME. For example, it can be used to
determine the event loop to which the file descriptor should be added.
GpgmeRemoveIOCb remove
GpgmeEventIOCb event
void *event_data
event function when
it is called by GPGME. For example, it can be used to
determine the context in which the event has occured.
gpgme_set_io_cbs enables the I/O callback
interface for the context ctx. The I/O callback functions are
specified by io_cbs.
If io_cbs->add is NULL, the I/O callback interface
is disabled for the context, and normal operation is restored.
gpgme_get_io_cbs returns the I/O callback
functions set with gpgme_set_io_cbs in io_cbs.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
To actually use an external event loop, you have to implement the I/O callback functions that are used by GPGME to register and unregister file descriptors. Furthermore, you have to actually monitor these file descriptors for activity and call the appropriate I/O callbacks.
The following example illustrates how to do that. The example uses locking to show in which way the the callbacks and the event loop can run concurrently. For the event loop, we use a fixed array. For a real-world implementation, you should use a dynamically sized structure because the number of file descriptors needed for a crypto operation in GPGME is not predictable.
#include <pthread.h>
#include <sys/types.h>
#include <gpgme.h>
/* The following structure holds the result of a crypto operation. */
struct op_result
{
int done;
GpgmeError err;
};
/* The following structure holds the data associated with one I/O
callback. */
struct one_fd
{
int fd;
int dir;
GpgmeIOCb fnc;
void *fnc_data;
};
struct event_loop
{
pthread_mutex_t lock;
#define MAX_FDS 32
/* Unused slots are marked with FD being -1. */
struct one_fd fds[MAX_FDS];
};
|
The following functions implement the I/O callback interface.
GpgmeError
add_io_cb (void *data, int fd, int dir, GpgmeIOCb fnc, void *fnc_data,
void **r_tag)
{
struct event_loop *loop = data;
struct one_fd *fds = loop->fds;
int i;
pthread_mutex_lock (&loop->lock);
for (i = 0; i < MAX_FDS; i++)
{
if (fds[i].fd == -1)
{
fds[i].fd = fd;
fds[i].dir = dir;
fds[i].fnc = fnc;
fds[i].fnc_data = fnc_data;
break;
}
}
pthread_mutex_unlock (&loop->lock);
if (i == MAX_FDS)
return GPGME_General_Error;
*r_tag = &fds[i];
return 0;
}
void
remove_io_cb (void *tag)
{
struct one_fd *fd = tag;
pthread_mutex_lock (&loop->lock);
fd->fd = -1;
pthread_mutex_unlock (&loop->lock);
}
void
event_io_cb (void *data, GpgmeEventIO type, void *type_data)
{
struct op_result *result = data;
GpgmeError *err = data;
/* We don't support list operations here. */
if (type == GPGME_EVENT_DONE)
{
result->done = 1;
result->err = *data;
}
}
|
The final missing piece is the event loop, which will be presented next. We only support waiting for the success of a single operation.
int
do_select (struct event_loop *loop)
{
fd_set rfds;
fd_set wfds;
int i, n;
int any = 0;
pthread_mutex_lock (&loop->lock);
FD_ZERO (&rfds);
FD_ZERO (&wfds);
for (i = 0; i < FDLIST_MAX; i++)
if (fdlist[i].fd != -1)
FD_SET (fdlist[i].fd, fdlist[i].dir ? &rfds : &wfds);
pthread_mutex_unlock (&loop->unlock);
do
{
n = select (FD_SETSIZE, &rfds, &wfds, NULL, 0);
}
while (n < 0 && errno == EINTR);
if (n < 0)
return n; /* Error or timeout. */
pthread_mutex_lock (&loop->lock);
for (i = 0; i < FDLIST_MAX && n; i++)
{
if (fdlist[i].fd != -1)
{
if (FD_ISSET (fdlist[i].fd, fdlist[i].dir ? &rfds : &wfds))
{
assert (n);
n--;
any = 1;
/* The I/O callback handler can register/remove callbacks,
so we have to unlock the file descriptor list. */
pthread_mutex_unlock (&loop->lock);
(*fdlist[i].fnc) (fdlist[i].fnc_data, fdlist[i].fd);
pthread_mutex_lock (&loop->lock);
}
}
}
pthread_mutex_unlock (&loop->lock);
return any;
}
void
wait_for_op (struct event_loop *loop, struct op_result *result)
{
int ret;
do
{
ret = do_select (loop);
}
while (ret >= 0 && !result->done);
return ret;
}
|
The main function shows how to put it all together.
int
main (int argc, char *argv[])
{
struct event_loop loop;
struct op_result result;
GpgmeCtx ctx;
GpgmeError err;
GpgmeData sig, text;
GpgmeSigStat status;
int i;
struct GpgmeIOCbs io_cbs =
{
add_io_cb,
&loop,
remove_io_cb,
event_io_cb,
&result
};
/* Initialize the loop structure. */
loop.lock = PTHREAD_MUTEX_INITIALIZER;
for (i = 0; i < MAX_FDS; i++)
loop->fds[i].fd = -1;
/* Initialize the result structure. */
result.done = 0;
err = gpgme_data_new_from_file (&sig, "signature", 1);
if (!err)
err = gpgme_data_new_from_file (&text, "text", 1);
if (!err)
err = gpgme_new (&ctx);
if (!err)
{
gpgme_set_io_cbs (ctx, &io_cbs);
err = gpgme_op_verify_start (ctx, sig, text, &status);
}
if (err)
{
fprintf (stderr, "gpgme error: %s\n", gpgme_strerror (err));
exit (1);
}
wait_for_op (&loop, &result);
if (!result.done)
{
fprintf (stderr, "select error\n");
exit (1);
}
if (!result.err)
{
fprintf (stderr, "verification failed: %s\n", gpgme_strerror (result.err));
exit (1);
}
/* Evaluate STATUS. */
...
return 0;
}
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The I/O callback interface can be used to integrate GPGME with the GTK+ event loop. The following code snippets shows how this can be done using the appropriate register and remove I/O callback functions. In this example, the private data of the register I/O callback function is unused. The event notifications is missing because it does not require any GTK+ specific setup.
#include <gtk/gtk.h>
struct my_gpgme_io_cb
{
GpgmeIOCb fnc;
void *fnc_data;
guint input_handler_id
};
void
my_gpgme_io_cb (gpointer data, gint source, GdkInputCondition condition)
{
struct my_gpgme_io_cb *iocb = d
1109
ata;
(*(iocb->fnc)) (iocb->data, source);
}
void
my_gpgme_remove_io_cb (void *data)
{
struct my_gpgme_io_cb *iocb = data;
gtk_input_remove (data->input_handler_id);
}
void
my_gpgme_register_io_callback (void *data, int fd, int dir, GpgmeIOCb fnc,
void *fnc_data, void **tag)
{
struct my_gpgme_io_cb *iocb = g_malloc (sizeof (struct my_gpgme_io_cb));
iocb->fnc = fnc;
iocb->data = fnc_data;
iocb->input_handler_id = gtk_input_add_full (fd, dir
? GDK_INPUT_READ
: GDK_INPUT_WRITE,
my_gpgme_io_callback,
0, iocb, NULL);
*tag = iocb;
return 0;
}
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The I/O callback interface can also be used to integrate GPGME with the GDK event loop. The following code snippets shows how this can be done using the appropriate register and remove I/O callback functions. In this example, the private data of the register I/O callback function is unused. The event notifications is missing because it does not require any GDK specific setup.
It is very similar to the GTK+ example in the previous section.
#include <gdk/gdk.h>
struct my_gpgme_io_cb
{
GpgmeIOCb fnc;
void *fnc_data;
gint tag;
};
void
my_gpgme_io_cb (gpointer data, gint source, GdkInputCondition condition)
{
struct my_gpgme_io_cb *iocb = data;
(*(iocb->fnc)) (iocb->data, source);
}
void
my_gpgme_remove_io_cb (void *data)
{
struct my_gpgme_io_cb *iocb = data;
gdk_input_remove (data->tag);
}
void
my_gpgme_register_io_callback (void *data, int fd, int dir, GpgmeIOCb fnc,
void *fnc_data, void **tag)
{
struct my_gpgme_io_cb *iocb = g_malloc (sizeof (struct my_gpgme_io_cb));
iocb->fnc = fnc;
iocb->data = fnc_data;
iocb->tag = gtk_input_add_full (fd, dir ? GDK_INPUT_READ : GDK_INPUT_WRITE,
my_gpgme_io_callback, iocb, NULL);
*tag = iocb;
return 0;
}
|
| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |