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 */
46IMG4_API_AVAILABLE_20180112
47OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL3 OS_NONNULL5
48errno_t
49img4_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 */
64IMG4_API_AVAILABLE_20180112
65OS_EXPORT OS_NONNULL1
66void
67img4_payload_destroy(img4_payload_t *i4p);
68
69#endif // __IMG4_PAYLOAD_H
70
71