EXTERNAL_HEADERS/img4/payload.h

   1 /*!
   2  * @header
   3  * Image4 payload interfaces. These interfaces provide a lightweight type for
   4  * working with an Image4 payload that is described by a separate manifest (e.g.
   5  * a .im4p file whose contents are described by an object in a manifest from a
   6  * .im4m file).
   7  *
   8  * No direct access is provided to the raw payload bytes encapsulated by the
   9  * Image4 payload by design. The intent is that in order to access the raw
  10  * bytes, the payload object must be validated against a manifest object using
  11  * the {@link img4_get_trusted_external_payload} interface.
  12  */
  13 #ifndef __IMG4_PAYLOAD_H
  14 #define __IMG4_PAYLOAD_H
  15
  16 #ifndef __IMG4_INDIRECT
  17 #error "Please #include <img4/img4.h> instead of this file directly"
  18 #endif // __IMG4_INDIRECT
  19
  20 /*!
  21  * @function img4_payload_init
  22  *
  23  * @param i4p
  24  * A pointer to the payload object to initialize.
  25  *
  26  * @param tag
  27  * The expected tag for the payload.
  28  *
  29  * @param bytes
  30  * The buffer containing the Image4 payload.
  31  *
  32  * @param len
  33  * The length of the buffer.
  34  *
  35  * @param destructor
  36  * A pointer to a routine to dispose of the buffer. May be NULL if the buffer
  37  * does not require explicit disposal (e.g. the buffer is stack memory).
  38  *
  39  * @result
  40  * Upon success, zero is returned. Otherwise, one of the following error codes:
  41  *
  42  *     [EILSEQ]     The data is not valid Image4 data
  43  *     [EFTYPE]     The data does not contain an Image4 payload
  44  *     [ENOENT]     The bytes do not contain a payload for the specified tag
  45  */
  46 IMG4_API_AVAILABLE_20180112
  47 OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL3 OS_NONNULL5
  48 errno_t
  49 img4_payload_init(img4_payload_t *i4p, img4_tag_t tag,
  50                 const uint8_t *bytes, size_t len, img4_destructor_t destructor);
  51
  52 /*!
  53  * @function img4_payload_destroy
  54  * Disposes of the resources associated with the payload object.
  55  *
  56  * @param i4p
  57  * The payload object of which to dispose.
  58  *
  59  * @discussion
  60  * This routine does not deallocate the storage for the payload object itself,
  61  * only the associated resources. This routine will cause the destructor given
  62  * in {@link img4_payload_init} to be called, if any.
  63  */
  64 IMG4_API_AVAILABLE_20180112
  65 OS_EXPORT OS_NONNULL1
  66 void
  67 img4_payload_destroy(img4_payload_t *i4p);
  68
  69 #endif // __IMG4_PAYLOAD_H
  70