cdi_avm_payloads_api.h File Reference

This file declares the public API data types, structures and functions that facilitate parsing and synthesizing payloads that conform to CDI's baseline configuration. More...

#include "cdi_core_api.h"
#include <stdbool.h>
#include <stdint.h>

Go to the source code of this file.

Data Structures
struct	CdiAvmAncillaryDataPacket
	An ancillary data packet. See https://datatracker.ietf.org/doc/html/rfc8331#section-2.1 for details. More...

Macros
#define	CDI_MAX_ANC_USER_DATA_WORDS   (255)
	Maximum number of user data words per ancillary data packet (SMPTE ST 291-1 Section 6.6).

Typedefs
typedef const CdiAvmAncillaryDataPacket *	CdiAvmPacketizeAncCallback(void *context_ptr)
	Prototype of callback function used by CdiAvmPacketizeAncillaryData.
typedef void	CdiAvmUnpacketizeAncCallback(void *context_ptr, CdiFieldKind field_kind, const CdiAvmAncillaryDataPacket *packet_ptr, bool has_parity_error, bool has_checksum_error)
	Prototype of callback function used by CdiAvmUnpacketizeAncillaryData.

Enumerations
enum	CdiFieldKind { kCdiFieldKindUnspecified = 0 , kCdiFieldKindInvalid = 1 , kCdiFieldKindInterlacedFirst = 2 , kCdiFieldKindInterlacedSecond = 3 }

Functions
CDI_INTERFACE int	CdiAvmGetAncillaryDataPayloadSize (uint16_t num_anc_packets, uint8_t data_counts[])
CDI_INTERFACE CdiReturnStatus	CdiAvmPacketizeAncillaryData (CdiAvmPacketizeAncCallback *produce_next_packet_ptr, CdiFieldKind field_kind, void *context_ptr, char *buffer_ptr, int *size_in_bytes_ptr)
CDI_INTERFACE CdiReturnStatus	CdiAvmUnpacketizeAncillaryData (const CdiSgList *sgl_ptr, CdiAvmUnpacketizeAncCallback *consume_next_packet_ptr, void *context_ptr)

Detailed Description

This file declares the public API data types, structures and functions that facilitate parsing and synthesizing payloads that conform to CDI's baseline configuration.

Typedef Documentation

CdiAvmPacketizeAncCallback

typedef const CdiAvmAncillaryDataPacket * CdiAvmPacketizeAncCallback(void *context_ptr)

Prototype of callback function used by CdiAvmPacketizeAncillaryData.

This callback function is invoked one or multiple times by CdiAvmPacketizeAncillaryData. For each invocation the callback returns either a pointer to the next ancillary data packet structure to be encoded according to RFC 8331, or NULL when the ancillary data payload is complete.

The memory referenced by the returned pointer is owned by the application.

Parameters

context_ptr

Pointer to user-defined data to keep track of state.

Returns

Pointer to an CdiAvmAncillaryDataPacket or NULL.

CdiAvmUnpacketizeAncCallback

typedef void CdiAvmUnpacketizeAncCallback(void *context_ptr, CdiFieldKind field_kind, const CdiAvmAncillaryDataPacket *packet_ptr, bool has_parity_error, bool has_checksum_error)

Prototype of callback function used by CdiAvmUnpacketizeAncillaryData.

This callback function is invoked one or multiple times by CdiAvmUnpacketizeAncillaryData. For each invocation the callback receives either a pointer to the next decoded ancillary data packet, or NULL when the ancillary data payload is complete.

The field_kind value is read from the ancillary data payload header and is the same for every callback invocation of the payload. Parameters parity_error and checksum_error indicate whether a parity error or checksum error was detected during decoding of the ancillary data packet.

The memory referenced by packet_ptr is owned by the SDK.

Parameters

context_ptr	Pointer to user-defined data to keep track of state.
field_kind	Field kind value from the ancillary data payload header.
packet_ptr	Pointer to the decoded ancillary data packet.
has_parity_error	True when a header parity bit was wrong (did, sdid, and data_count have parity bits).
has_checksum_error	True when the packet's checksum was wrong.

Enumeration Type Documentation

CdiFieldKind

enum CdiFieldKind

Specifies what video field the timestamp in the ancillary data payload refers to. See also header field "F" in https://datatracker.ietf.org/doc/html/rfc8331#section-2.1.

Enumerator
kCdiFieldKindUnspecified	Indicates that no associated video field has been specified. Use with progressive scan mode.
kCdiFieldKindInvalid	Not a valid choice, receivers should ignore the payload.
kCdiFieldKindInterlacedFirst	Indicates that the payload timestamp refers to the first field of an interlaced video signal.
kCdiFieldKindInterlacedSecond	Indicates that the payload timestamp refers to the second field of an interlaced video signal.

Function Documentation

CdiAvmGetAncillaryDataPayloadSize()

CDI_INTERFACE int CdiAvmGetAncillaryDataPayloadSize	(	uint16_t	num_anc_packets,
		uint8_t	data_counts[] )

Calculate the buffer size needed to write an ancillary data payload.

Parameters

num_anc_packets	The number of ancillary data packets.
data_counts	Number of user data words for each prospective ancillary data packet (see CdiAvmAncillaryDataPacket).

Returns

Required buffer size in bytes.

CdiAvmPacketizeAncillaryData()

CDI_INTERFACE CdiReturnStatus CdiAvmPacketizeAncillaryData	(	CdiAvmPacketizeAncCallback *	produce_next_packet_ptr,
		CdiFieldKind	field_kind,
		void *	context_ptr,
		char *	buffer_ptr,
		int *	size_in_bytes_ptr )

Generate an ancillary data payload in the provided buffer. For each ancillary data packet the application's callback returns a pointer to an CdiAvmAncillaryDataPacket object; it returns NULL when the payload is complete. The packets produced by the callback are encoded in order. The whole payload is prefixed with a two-word header. See https://cdi.elemental.com/specs/baseline-ancillary-data for the payload format.

The provided buffer must be large enough to hold the encoded data. When the number of user data words of all ancillary data packets in the payload is known in advance, CdiAvmGetAncillaryDataPayloadSize may be used to compute the required buffer size.

Parameters

produce_next_packet_ptr	Callback provided by the application, producing next ancillary data packet to encode.
field_kind	Field kind of this payload. See CdiFieldKind.
context_ptr	Pointer to user-defined data to keep track of state.
buffer_ptr	Pointer to payload buffer.
size_in_bytes_ptr	Points to size in bytes of payload buffer. Points to size of payload on successful return.

Returns

Status code indicating success or failure.

CdiAvmUnpacketizeAncillaryData()

CDI_INTERFACE CdiReturnStatus CdiAvmUnpacketizeAncillaryData	(	const CdiSgList *	sgl_ptr,
		CdiAvmUnpacketizeAncCallback *	consume_next_packet_ptr,
		void *	context_ptr )

Decode an ancillary data payload from the provided buffer and pass decoded ancillary data packets to the provided callback function for processing. If the payload cannot be decoded then kCdiInvalidPayload is returned. A return code of kCdiStatusRxPayloadError indicates that the payload was decoded with parity or checksum errors detected.

Parameters

sgl_ptr	Pointer to payload buffer.
consume_next_packet_ptr	Callback provided by the application, consuming next decoded ancillary data packet.
context_ptr	Pointer to user-defined data to keep track of state.

Returns

Status code indicating success or failure.