baseline_profile.c File Reference

This file contains the functions and other definitions that comprise the CDI AVM baseline profile. More...

#include <assert.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "cdi_baseline_profile_api.h"
#include "cdi_logger_api.h"
#include "utilities_api.h"

Data Structures
struct	BaselineProfileData
	Type used to hold baseline profile version and V-table to required APIs. More...

Macros
#define	PROFILES_MAX   (10)
	Value used to define the maximum number of profiles stored for each profile type.

Functions
static CdiBaselineAvmPayloadType	EnumStringKeyTypeToPayloadType (CdiAvmBaselineEnumStringKeyTypes key_type)
	Convert an enum key type to a profile type (same thing as payload type).
static CdiReturnStatus	InitializeBaselineProfiles (void)
static BaselineProfileData *	FindProfileVersion (CdiBaselineAvmPayloadType payload_type, const CdiAvmBaselineProfileVersion *version_ptr, bool warn_not_found)
	Find the baseline profile for the specified payload type and version.
CdiReturnStatus	CdiAvmRegisterBaselineProfile (CdiBaselineAvmPayloadType media_type, const char *profile_version_str, CdiAvmVTableApi *vtable_api_ptr)
	Register a baseline profile.
CdiReturnStatus	CdiAvmMakeBaselineConfiguration (const CdiAvmBaselineConfig *baseline_config_ptr, CdiAvmConfig *config_ptr, int *payload_unit_size_ptr)
CdiReturnStatus	CdiAvmMakeBaselineConfiguration2 (const CdiAvmBaselineConfigCommon *baseline_config_ptr, CdiAvmConfig *config_ptr, int *payload_unit_size_ptr)
	New version of the existing CdiAvmMakeBaselineConfiguration() API that supports a generic extensible baseline configuration structure. For more details see CdiAvmMakeBaselineConfiguration().
CdiReturnStatus	CdiAvmParseBaselineConfiguration (const CdiAvmConfig *config_ptr, CdiAvmBaselineConfig *baseline_config_ptr)
	Converts from the AVM configuration structure to the CDI baseline configuration structure if possible. This is to be called on the receive side if the CdiAvmConfig structure is provided to the registered receive payload callback function. This function must be called whenever the config_ptr is non-NULL as the first step in determining the stream's configuration. If kCdiStatusOk is returned, then the configuration belongs to the CDI baseline profile described by the structure filled in at baseline_config_ptr. A code other than kCdiStatusOk is returned when the configuration is not recognized as a supported baseline profile. An AVM configuration not convertible to a CDI baseline configuration must be parsed by an application-specific function.
CdiReturnStatus	CdiAvmParseBaselineConfiguration2 (const CdiAvmConfig *config_ptr, CdiAvmBaselineConfigCommon *baseline_config_ptr)
CdiReturnStatus	CdiAvmGetBaselineUnitSize (const CdiAvmBaselineConfig *baseline_config_ptr, int *payload_unit_size_ptr)
	Gets the unit size in bits for transmission of the media as specified by the configuration structure.
CdiReturnStatus	CdiAvmGetBaselineUnitSize2 (const CdiAvmBaselineConfigCommon *baseline_config_ptr, int *payload_unit_size_ptr)
	New version of the existing CdiAvmGetBaselineUnitSize() API that supports a generic extensible baseline configuration structure. For more details see CdiAvmGetBaselineUnitSize().
const char *	CdiAvmKeyEnumToString (CdiAvmBaselineEnumStringKeyTypes key_type, int enum_value, const CdiAvmBaselineProfileVersion *version_ptr)
int	CdiAvmKeyStringToEnum (CdiAvmBaselineEnumStringKeyTypes key_type, const char *name_str, const CdiAvmBaselineProfileVersion *version_ptr)
const CdiEnumStringKey *	CdiAvmKeyGetArray (CdiAvmBaselineEnumStringKeyTypes key_type, const CdiAvmBaselineProfileVersion *version_ptr)
bool	CdiAvmParseBaselineVersionString (const char *version_str, CdiAvmBaselineProfileVersion *ret_version_ptr)
CdiReturnStatus	CdiAvmValidateBaselineVersionString (CdiBaselineAvmPayloadType media_type, const char *version_str, CdiAvmBaselineProfileVersion *ret_version_ptr)

Variables
static int	initialized = false
	Used to determine if static instance data used within this file has been initialized.
static CdiStaticMutexType	mutex_lock = CDI_STATIC_MUTEX_INITIALIZER
	Statically allocated mutex used to make initialization of profile data thread-safe.
static BaselineProfileData	baseline_profile_array [CDI_BASELINE_AVM_PAYLOAD_TYPE_ENUM_COUNT][PROFILES_MAX] = {0}
	Array of baseline profiles, with version and V-tables for each one. Indexed by profile type.
static int	profile_type_count_array [CDI_BASELINE_AVM_PAYLOAD_TYPE_ENUM_COUNT] = {0}
	Array of number of profiles for each profile type.
static const CdiEnumStringKey	avm_uri_strings []
static const CdiEnumStringKey	payload_type_key_array []
	Enum/string keys for CdiAvmPayloadType.

Detailed Description

This file contains the functions and other definitions that comprise the CDI AVM baseline profile.

Function Documentation

CdiAvmGetBaselineUnitSize()

CdiReturnStatus CdiAvmGetBaselineUnitSize	(	const CdiAvmBaselineConfig *	baseline_config_ptr,
		int *	payload_unit_size_ptr )

Gets the unit size in bits for transmission of the media as specified by the configuration structure.

Parameters

baseline_config_ptr	The address of a configuration structure whose unit size is of interest.
payload_unit_size_ptr	Pointer to location where the unit bit length is to be written.

Returns

CdiReturnStatus kCdiStatusOk if the configuration structure was correct enough to determine a unit size, otherwise kCdiStatusFatal.

CdiAvmKeyEnumToString()

const char * CdiAvmKeyEnumToString	(	CdiAvmBaselineEnumStringKeyTypes	key_type,
		int	enum_value,
		const CdiAvmBaselineProfileVersion *	version_ptr )

Function used to convert an enum value to a string.

Parameters

key_type	Enum which indicates which key-value array to search for enum_value.
enum_value	Value to convert to a string.
version_ptr	Pointer to profile version to use. If NULL, profile version 01.00 is used.

Returns

Pointer to returned string. If no match was found, NULL is returned.

CdiAvmKeyGetArray()

const CdiEnumStringKey * CdiAvmKeyGetArray	(	CdiAvmBaselineEnumStringKeyTypes	key_type,
		const CdiAvmBaselineProfileVersion *	version_ptr )

Function used to get a pointer to a key-value array of a type specified by key_type.

Parameters

key_type	Enum from EnumStringKeyTypes which indicates which key-value array to return.
version_ptr	Pointer to profile version to use. If NULL, profile version 01.00 is used.

Returns

Pointer to returned string. If no match was found, NULL is returned.

CdiAvmKeyStringToEnum()

int CdiAvmKeyStringToEnum	(	CdiAvmBaselineEnumStringKeyTypes	key_type,
		const char *	name_str,
		const CdiAvmBaselineProfileVersion *	version_ptr )

Function used to convert a string to a matching enum value.

Parameters

key_type	Enum which indicates which key-value array to search for name_str.
name_str	Pointer to string name of enumerated value.
version_ptr	Pointer to profile version to use. If NULL, profile version 01.00 is used.

Returns

Returned enumerated value. If no match was found, CDI_INVALID_ENUM_VALUE is returned.

CdiAvmMakeBaselineConfiguration()

CdiReturnStatus CdiAvmMakeBaselineConfiguration	(	const CdiAvmBaselineConfig *	baseline_config_ptr,
		CdiAvmConfig *	config_ptr,
		int *	payload_unit_size_ptr )

Converts from the simple, constrained baseline configuration structures to the more general purpose CdiAvmConfig structure used in the AVM interface. This is useful on the transmit side for streams that comply with the baseline CDI profile for inter-vendor compatibility.

NOTE: Newly created data structures that are passed in to this function should be properly initialized before being programmed with user values. Use memset or a zero structure initializer (= {0}) to set the whole structure to zero before setting the desired members to the actual values required.

Parameters

baseline_config_ptr	Address of the source configuration structure.
config_ptr	Address of where to write the resulting AVM configuration structure.
payload_unit_size_ptr	Address of where to write the payload unit size which is used by the transmit packetizer. This value should be passed in the unit_size member of the payload_config_ptr->core_config_data structure when calling CdiAvmTxPayload().

Returns

CdiReturnStatus kCdiStatusOk if the conversion was successful, kCdiStatusFatal if config_ptr is NULL or the baseline configuration

CdiAvmParseBaselineConfiguration()

CdiReturnStatus CdiAvmParseBaselineConfiguration	(	const CdiAvmConfig *	config_ptr,
		CdiAvmBaselineConfig *	baseline_config_ptr )

Converts from the AVM configuration structure to the CDI baseline configuration structure if possible. This is to be called on the receive side if the CdiAvmConfig structure is provided to the registered receive payload callback function. This function must be called whenever the config_ptr is non-NULL as the first step in determining the stream's configuration. If kCdiStatusOk is returned, then the configuration belongs to the CDI baseline profile described by the structure filled in at baseline_config_ptr. A code other than kCdiStatusOk is returned when the configuration is not recognized as a supported baseline profile. An AVM configuration not convertible to a CDI baseline configuration must be parsed by an application-specific function.

Parameters

config_ptr	Pointer to the AVM configuration structure provided to the registered receive payload callback function.
baseline_config_ptr	Address where baseline configuration structure parameters are written to when the return code is kCdiStatusOk. When the return code is kCdiStatusProfileNotSupported, then only payload_type is written. For any other return code no parameters are written.

Returns

kCdiStatusOk if conversion to CDI baseline configuration was successful; kCdiStatusFatal if a CDI baseline configuration was recognized but baseline_config_ptr is NULL; kCdiStatusNonFatal when the AVM configuration structure could not be interpreted or did not meet specifications; kCdiStatusProfileNotSupported when a CDI profile version was parsed but no corresponding baseline profile was found.

CdiAvmParseBaselineConfiguration2()

CdiReturnStatus CdiAvmParseBaselineConfiguration2	(	const CdiAvmConfig *	config_ptr,
		CdiAvmBaselineConfigCommon *	baseline_config_ptr )

New version of the existing CdiAvmParseBaselineConfiguration() API that supports a generic extensible baseline configuration structure. For more details see CdiAvmParseBaselineConfiguration().

CdiAvmParseBaselineVersionString()

bool CdiAvmParseBaselineVersionString	(	const char *	version_str,
		CdiAvmBaselineProfileVersion *	ret_version_ptr )

Converts a string representing a baseline configuration structure version number in the form of "xx.yy" into a structure with major and minor members.

Parameters

version_str	The source string to convert.
ret_version_ptr	The address of the structure to write the version numbers into.

Returns

true if the conversion was successful, false if a failure was encountered.

CdiAvmRegisterBaselineProfile()

CdiReturnStatus CdiAvmRegisterBaselineProfile	(	CdiBaselineAvmPayloadType	media_type,
		const char *	profile_version_str,
		CdiAvmVTableApi *	vtable_api_ptr )

Register a baseline profile.

Parameters

media_type	Enum which indicates the type of payload data (ie. video, audio or ancillary data).
profile_version_str	Pointer to profile version string. Must be in "xx.xx" format.
vtable_api_ptr	Pointer to V-table to use for required baseline profile APIs.

Returns

kCdiStatusOk if ok. kCdiStatusArraySizeExceeded if array size has been exceeded, otherwise kCdiStatusFatal.

CdiAvmValidateBaselineVersionString()

CdiReturnStatus CdiAvmValidateBaselineVersionString	(	CdiBaselineAvmPayloadType	media_type,
		const char *	version_str,
		CdiAvmBaselineProfileVersion *	ret_version_ptr )

Parses a baseline configuration version number from a string of the form of "xx.yy". When the string represents a registered baseline configuration version, writes the version numbers into the provided output structure.

Parameters

media_type	Enum which indicates the type of payload data (ie. video, audio or ancillary data).
version_str	The source string to convert.
ret_version_ptr	The address of the structure to write the version numbers into.

Returns

Returns kCdiStatusOk if and only if the source string represents a known baseline configuration.

EnumStringKeyTypeToPayloadType()

static CdiBaselineAvmPayloadType EnumStringKeyTypeToPayloadType ( CdiAvmBaselineEnumStringKeyTypes key_type )

static

Convert an enum key type to a profile type (same thing as payload type).

Parameters

key_type

Enum value of key type to convert.

Returns

Enum value of profile type.

FindProfileVersion()

static BaselineProfileData * FindProfileVersion ( CdiBaselineAvmPayloadType payload_type, const CdiAvmBaselineProfileVersion * version_ptr, bool warn_not_found )

static

Find the baseline profile for the specified payload type and version.

Parameters

payload_type	Enum value of payload type (same as profile type)
version_ptr	Pointer to version to find. If NULL, finds first profile in table.
warn_not_found	When true, generate a warning when profile data could not be found.

Returns

Pointer to found profile. NULL if none found.

InitializeBaselineProfiles()

static CdiReturnStatus InitializeBaselineProfiles ( void )

static

Initialize the AVM layer of the CDI-SDK.

Returns

A value from the CdiReturnStatus enumeration.

Variable Documentation

avm_uri_strings

const CdiEnumStringKey avm_uri_strings[]

static

Initial value:

= {
    
    { kCdiAvmVideo,     "https://cdi.elemental.com/specs/baseline-video" },
    { kCdiAvmAudio,     "https://cdi.elemental.com/specs/baseline-audio" },
    { kCdiAvmAncillary, "https://cdi.elemental.com/specs/baseline-ancillary-data" },
    { CDI_INVALID_ENUM_VALUE, NULL } 
}

Table for converting between the supported AVM media types and the URIs associated with them.

payload_type_key_array

const CdiEnumStringKey payload_type_key_array[]

static

Initial value:

= {
    { kCdiAvmNotBaseline, "not baseline" },
    { kCdiAvmVideo,       "Video" },
    { kCdiAvmAudio,       "Audio" },
    { kCdiAvmAncillary,   "Ancillary" },
    { CDI_INVALID_ENUM_VALUE, NULL } 
}

Enum/string keys for CdiAvmPayloadType.