GNU Info

(gpgme.info)Creating Data Buffers

---

Next: Destroying Data Buffers Up: Exchanging Data

---

Enter node , (file) or (file)node

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.