Creating Data Buffers
=====================
- Function: GpgmeError gpgme_data_new (GpgmeData *DH)
The function `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.
- Function: GpgmeError gpgme_data_new_from_mem (GpgmeData *DH,
const char *BUFFER, size_t SIZE, int COPY)
The function `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.
- Function: GpgmeError gpgme_data_new_from_file (GpgmeData *DH,
const char *FILENAME, int COPY)
The function `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.
- Function: GpgmeError gpgme_data_new_from_filepart (GpgmeData *DH,
const char *FILENAME, FILE *FP, off_t OFFSET, size_t LENGTH)
The function `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.
- Function: GpgmeError gpgme_data_new_with_read_cb (GpgmeData *DH,
int (*READFUNC) (void *HOOK, char *BUFFER, size_t COUNT,
size_t *NREAD), void *HOOK_VALUE)
The function `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.