[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A lot of data has to be exchanged between the user and the crypto
engine, like plaintext messages, ciphertext, signatures and
information about the keys. The technical details about exchanging
the data information are completely abstracted by GPGME.
The user provides and receives the data via GpgmeData
objects,
regardless of the communication protocol between GPGME and
the crypto engine in use.
GpgmeData
type is a handle for a container for generic
data, which is used by GPGME to exchange data with the user.
5.1 Creating Data Buffers Creating new data buffers. 5.2 Destroying Data Buffers Releasing data buffers. 5.3 Manipulating Data Buffers Operations on data buffers.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_data_new
creates a new GpgmeData
object and returns a handle for it in dh. The data object is
initially empty.
The function returns GPGME_No_Error
if the data object was
successfully created, GPGME_Invalid_Value
if dh is not a
valid pointer, and GPGME_Out_Of_Core
if not enough memory is
available.
gpgme_data_new_from_mem
creates a new
GpgmeData
object and fills it with size bytes starting
from buffer.
If copy is not zero, a private copy of the data is made. If copy is zero, the data is taken from the specified buffer as needed, and the user has to ensure that the buffer remains valid for the whole life span of the data object.
The function returns GPGME_No_Error
if the data object was
successfully created, GPGME_Invalid_Value
if dh or
buffer is not a valid pointer, and GPGME_Out_Of_Core
if
not enough memory is available.
gpgme_data_new_from_file
creates a new
GpgmeData
object and fills it with the content of the file
filename.
If copy is not zero, the whole file is read in at initialization time and the file is not used anymore after that. This is the only mode supported currently. Later, a value of zero for copy might cause all reads to be delayed until the data is needed, but this is not yet implemented.
The function returns GPGME_No_Error
if the data object was
successfully created, GPGME_Invalid_Value
if dh or
filename is not a valid pointer, GPGME_File_Error
if an
I/O operation fails, GPGME_Not_Implemented
if code is
zero, and GPGME_Out_Of_Core
if not enough memory is available.
gpgme_data_new_from_filepart
creates a new
GpgmeData
object and fills it with a part of the file specified
by filename or fp.
Exactly one of filename and fp must be non-zero, the other must be zero. The argument that is not zero specifies the file from which length bytes are read into the data object, starting from offset.
The function returns GPGME_No_Error
if the data object was
successfully created, GPGME_Invalid_Value
if dh and
exactly one of filename and fp is not a valid pointer,
GPGME_File_Error
if an I/O operation fails, and
GPGME_Out_Of_Core
if not enough memory is available.
gpgme_data_new_with_read_cb
creates a new
GpgmeData
object and uses the callback function readfunc
to retrieve the data on demand. As the callback function can supply
the data in any way it wants, this is the most flexible data type
GPGME provides. However, it can not be used to write data.
The callback function receives hook_value as its first argument
whenever it is invoked. It should return up to count bytes in
buffer, and return the number of bytes actually read in
nread. It may return 0
in nread if no data is
currently available. To indicate EOF
the function should
return with an error code of -1
and set nread to
0
. The callback function may support to reset its internal
read pointer if it is invoked with buffer and nread being
NULL
and count being 0
.
The function returns GPGME_No_Error
if the data object was
successfully created, GPGME_Invalid_Value
if dh or
readfunc is not a valid pointer, and GPGME_Out_Of_Core
if
not enough memory is available.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_data_release
destroys the data object with
the handle dh. It releases all associated resources that were
not provided by the user in the first place.
gpgme_data_release_and_get_mem
is like
gpgme_data_release
, except that it returns the data buffer and
its length that was provided by the object.
The user has to release the buffer with free
. In case the user
provided the data buffer in non-copy mode, a copy will be made for
this purpose.
In case an error returns, or there is no suitable data buffer that can
be returned to the user, the function will return NULL
.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_data_read
reads up to length bytes
from the data object with the handle dh into the space starting
at buffer. The actual amount read is returned in nread.
If buffer is NULL
, the function returns the amount of
bytes available in nread without changing the read pointer.
This is not supported by all types of data objects. If this function
is not supported, GPGME_Invalid_Type
is returned.
If the end of the data object is reached, the function returns
GPGME_EOF
and sets nread to zero.
In all other cases, the function returns GPGME_No_Error
if the
operation was successfully performed and GPGME_Invalid_Value
if
dh is not a valid pointer.
gpgme_data_rewind
resets the read pointer of the
data object with the handle dh, so that a subsequent
gpgme_data_read
operation starts at the beginning of the data.
The function returns GPGME_No_Error
if the operation was
successfully performed, GPGME_Not_Implemented
if the operation
is not supported (for example, by a read callback function supplied by
the user) and GPGME_Invalid_Value
if dh is not a valid
pointer.
gpgme_data_write
writes length bytes
starting from buffer into the data object with the handle
dh at the current write position.
The function returns GPGME_No_Error
if the operation was
successfully performed, GPGME_Invalid_Value
if dh or
buffer is not a valid pointer, GPGME_Invalid_Type
or
GPGME_Invalid_Mode
if the data object type does not support
writing, and GPGME_Out_Of_Core
if not enough memory is
available.
GpgmeDataType
type specifies the type of a GpgmeData
object.
The following data types are available:
GPGME_DATA_TYPE_NONE
GPGME_DATA_TYPE_MEM
GPGME_DATA_TYPE_FD
GPGME_DATA_TYPE_FILE
GPGME_DATA_TYPE_CB
gpgme_data_get_type
returns the type of the data
object with the handle dh. If dh is not a valid pointer,
GPGME_DATA_TYPE_NONE
is returned.
GpgmeDataEncoding
type specifies the encoding of a
GpgmeData
object. This encoding is useful to give the backend
a hint on the type of data. The following data types are available:
GPGME_DATA_ENCODING_NONE
GPGME_DATA_ENCODING_BINARY
GPGME_DATA_ENCODING_BASE64
GPGME_DATA_ENCODING_ARMOR
gpgme_data_get_encoding
returns the encoding of
the data object with the handle dh. If dh is not a valid
pointer (e.g. NULL
) GPGME_DATA_ENCODING_NONE
is
returned.
gpgme_data_set_encoding
changes the encoding of
the data object with the handle dh to enc.
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |