[apple/xnu.git] / EXTERNAL_HEADERS / img4 / payload.h

/*!
 * @header
 * Image4 payload interfaces. These interfaces provide a lightweight type for
 * working with an Image4 payload that is described by a separate manifest (e.g.
 * a .im4p file whose contents are described by an object in a manifest from a
 * .im4m file).
 *
 * No direct access is provided to the raw payload bytes encapsulated by the
 * Image4 payload by design. The intent is that in order to access the raw
 * bytes, the payload object must be validated against a manifest object using
 * the {@link img4_get_trusted_external_payload} interface.
 */
#ifndef __IMG4_PAYLOAD_H
#define __IMG4_PAYLOAD_H

#ifndef __IMG4_INDIRECT
#error "Please #include <img4/img4.h> instead of this file directly"
#endif // __IMG4_INDIRECT

/*!
 * @function img4_payload_init
 *
 * @param i4p
 * A pointer to the payload object to initialize.
 *
 * @param tag
 * The expected tag for the payload.
 *
 * @param bytes
 * The buffer containing the Image4 payload.
 *
 * @param len
 * The length of the buffer.
 *
 * @param destructor
 * A pointer to a routine to dispose of the buffer. May be NULL if the buffer
 * does not require explicit disposal (e.g. the buffer is stack memory).
 *
 * @result
 * Upon success, zero is returned. Otherwise, one of the following error codes:
 *
 *     [EILSEQ]     The data is not valid Image4 data
 *     [EFTYPE]     The data does not contain an Image4 payload
 *     [ENOENT]     The bytes do not contain a payload for the specified tag
 */
IMG4_API_AVAILABLE_20180112
OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL3 OS_NONNULL5
errno_t
img4_payload_init(img4_payload_t *i4p, img4_tag_t tag,
		const uint8_t *bytes, size_t len, img4_destructor_t destructor);

/*!
 * @function img4_payload_destroy
 * Disposes of the resources associated with the payload object.
 *
 * @param i4p
 * The payload object of which to dispose.
 *
 * @discussion
 * This routine does not deallocate the storage for the payload object itself,
 * only the associated resources. This routine will cause the destructor given
 * in {@link img4_payload_init} to be called, if any.
 */
IMG4_API_AVAILABLE_20180112
OS_EXPORT OS_NONNULL1
void
img4_payload_destroy(img4_payload_t *i4p);

#endif // __IMG4_PAYLOAD_H
Commit	Line	Data
d9a64523 A	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