| [ < ] | [ > ] | [ << ] | [ 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] | [ ? ] |