Properties class. More...

#include <mlt_properties.h>

Inheritance diagram for mlt_properties_s:

Public Member Functions
void	mlt_properties_close (mlt_properties self)
	Close a properties object.
int	mlt_properties_count (mlt_properties self)
	Return the number of items in the list.
void	mlt_properties_debug (mlt_properties self, const char title, FILE output)
	Output the properties to a file handle.
int	mlt_properties_dec_ref (mlt_properties self)
	Decrement the reference count.
int	mlt_properties_dir_list (mlt_properties self, const char dirname, const char pattern, int sort)
	Get the contents of a directory.
void	mlt_properties_dump (mlt_properties self, FILE *output)
	Dump the properties to a file handle.
char *	mlt_properties_get (mlt_properties self, const char *name)
	Get a string value by name.
void *	mlt_properties_get_data (mlt_properties self, const char name, int length)
	Get a binary data value associated to the name.
void *	mlt_properties_get_data_at (mlt_properties self, int index, int *size)
	Get a data value by index.
double	mlt_properties_get_double (mlt_properties self, const char *name)
	Get a floating point value associated to the name.
int	mlt_properties_get_int (mlt_properties self, const char *name)
	Get an integer associated to the name.
int64_t	mlt_properties_get_int64 (mlt_properties self, const char *name)
	Get a 64-bit integer associated to the name.
const char *	mlt_properties_get_lcnumeric (mlt_properties self)
	Get the numeric locale for this properties object.
char *	mlt_properties_get_name (mlt_properties self, int index)
	Get a property name by index.
mlt_position	mlt_properties_get_position (mlt_properties self, const char *name)
	Get a position value associated to the name.
char *	mlt_properties_get_value (mlt_properties self, int index)
	Get a property's string value by index.
int	mlt_properties_inc_ref (mlt_properties self)
	Increment the reference count.
int	mlt_properties_inherit (mlt_properties self, mlt_properties that)
	Copy all serializable properties to another properties list.
int	mlt_properties_init (mlt_properties self, void *child)
	Initialize a properties object that was already allocated.
int	mlt_properties_is_sequence (mlt_properties properties)
	Determine if the properties list is really just a sequence or ordered list.
mlt_properties	mlt_properties_load (const char *filename)
	Create a properties object by reading a .properties text file.
void	mlt_properties_lock (mlt_properties self)
	Protect a properties list against concurrent access.
void	mlt_properties_mirror (mlt_properties self, mlt_properties that)
	Set a properties list to be a mirror copy of another.
mlt_properties	mlt_properties_new ()
	Create a properties object.
int	mlt_properties_parse (mlt_properties self, const char *namevalue)
	Set a value by parsing a name=value string.
mlt_properties	mlt_properties_parse_yaml (const char *filename)
	Parse a YAML Tiny file by name.
int	mlt_properties_pass (mlt_properties self, mlt_properties that, const char *prefix)
	Pass all serializable properties that match a prefix to another properties object.
int	mlt_properties_pass_list (mlt_properties self, mlt_properties that, const char *list)
	Copy all properties specified in a comma-separated list to another properties list.
void	mlt_properties_pass_property (mlt_properties self, mlt_properties that, const char *name)
	Copy a property to another properties list.
int	mlt_properties_preset (mlt_properties self, const char *name)
	Set properties from a preset.
int	mlt_properties_ref_count (mlt_properties self)
	Get the reference count.
int	mlt_properties_rename (mlt_properties self, const char source, const char dest)
	Rename a property.
int	mlt_properties_save (mlt_properties self, const char *filename)
	Save the properties to a file by name.
char *	mlt_properties_serialise_yaml (mlt_properties self)
	Serialize a properties list as a string of YAML Tiny.
int	mlt_properties_set (mlt_properties self, const char name, const char value)
	Set a property to a string.
int	mlt_properties_set_data (mlt_properties self, const char name, void value, int length, mlt_destructor destroy, mlt_serialiser serialise)
	Store binary data as a property.
int	mlt_properties_set_double (mlt_properties self, const char *name, double value)
	Set a property to a floating point value.
int	mlt_properties_set_int (mlt_properties self, const char *name, int value)
	Set a property to an integer value.
int	mlt_properties_set_int64 (mlt_properties self, const char *name, int64_t value)
	Set a property to a 64-bit integer value.
int	mlt_properties_set_lcnumeric (mlt_properties self, const char *locale)
	Set the numeric locale used for string/double conversions.
int	mlt_properties_set_or_default (mlt_properties self, const char name, const char value, const char *def)
	Set or default a property to a string.
int	mlt_properties_set_position (mlt_properties self, const char *name, mlt_position value)
	Set a property to a position value.
void	mlt_properties_unlock (mlt_properties self)
	End protecting a properties list against concurrent access.
Data Fields
mlt_destructor	close
	the destructor virtual function
void *	close_object
	the object supplied to the close virtual function
Private Member Functions
static int	generate_hash (const char *name)
	Generate a hash key.
static int	mlt_compare (const void self, const void that)
	Compare the string or serialized value of two properties.
static int	mlt_fnmatch (const char wild, const char file)
	Test whether a filename or pathname matches a shell-style pattern.
static mlt_property	mlt_properties_add (mlt_properties self, const char *name)
	Add a new property.
static void	mlt_properties_do_mirror (mlt_properties self, const char *name)
	Copy a serializable property to a properties list that is mirroring this one.
static mlt_property	mlt_properties_fetch (mlt_properties self, const char *name)
	Fetch a property by name and add one if not found.
static mlt_property	mlt_properties_find (mlt_properties self, const char *name)
	Locate a property by name.
static void	serialise_yaml (mlt_properties self, strbuf output, int indent, int is_parent_sequence)
	Recursively serialize a properties list into a string buffer as YAML Tiny.
Private Attributes
void *	child
	the object of a subclass
void *	local
	instance object

Detailed Description

Properties class.

Properties is a combination list/dictionary of name/mlt_property pairs. It is also a base class for many of the other MLT classes.

Member Function Documentation

static int generate_hash ( const char * name ) [inline, private]

Generate a hash key.

Parameters:

name a string

Returns:: an integer

static int mlt_compare	(	const void *	self,
		const void *	that
	)		`[private]`

Compare the string or serialized value of two properties.

Parameters:

self	a property
that	a property

Returns:: < 0 if self less than that, 0 if equal, or > 0 if self is greater than that

static int mlt_fnmatch	(	const char *	wild,
		const char *	file
	)		`[private]`

Test whether a filename or pathname matches a shell-style pattern.

Parameters:

wild	a string containing a wildcard pattern
file	the name of a file to test against

Returns:: true if the file name matches the wildcard pattern

static mlt_property mlt_properties_add	(	mlt_properties	self,
		const char *	name
	)		`[private]`

Add a new property.

Parameters:

self	a properties list
name	the name of the new property

Returns:: the new property

void mlt_properties_close ( mlt_properties self )

Close a properties object.

Deallocates the properties object and everything it contains.

Parameters:

self	a properties object

int mlt_properties_count ( mlt_properties self )

Return the number of items in the list.

Parameters:

self	a properties list

Returns:: the number of property objects

void mlt_properties_debug	(	mlt_properties	self,
		const char *	title,
		FILE *	output
	)

Output the properties to a file handle.

This version includes reference counts and does not put each property on a new line.

Parameters:

self	a properties pointer
title	a string to preface the output
output	a file handle

int mlt_properties_dec_ref ( mlt_properties self )

Decrement the reference count.

Parameters:

self	a properties list

Returns:: the new reference count

int mlt_properties_dir_list	(	mlt_properties	self,
		const char *	dirname,
		const char *	pattern,
		int	sort
	)

Get the contents of a directory.

Obtains an optionally sorted list of the files found in a directory with a specific wild card. Entries in the list have a numeric name (running from 0 to count - 1). Only values change position if sort is enabled. Designed to be posix compatible (linux, os/x, mingw etc).

Parameters:

self	a properties list
dirname	the name of the directory
pattern	a wildcard pattern to filter the directory listing
sort	Do you want to sort the directory listing?

Returns:: the number of items in the directory listing

static void mlt_properties_do_mirror	(	mlt_properties	self,
		const char *	name
	)		`[inline, private]`

Copy a serializable property to a properties list that is mirroring this one.

Special case - when a container (such as loader) is protecting another producer, we need to ensure that properties are passed through to the real producer.

Parameters:

self	a properties list
name	the name of the property to copy

void mlt_properties_dump	(	mlt_properties	self,
		FILE *	output
	)

Dump the properties to a file handle.

Parameters:

self	a properties list
output	a file handle

static mlt_property mlt_properties_fetch	(	mlt_properties	self,
		const char *	name
	)		`[private]`

Fetch a property by name and add one if not found.

Parameters:

self	a properties list
name	the property to lookup or add

Returns:: the property

static mlt_property mlt_properties_find	(	mlt_properties	self,
		const char *	name
	)		`[inline, private]`

Locate a property by name.

Parameters:

self	a properties list
name	the property to lookup by name

Returns:: the property or NULL for failure

char * mlt_properties_get	(	mlt_properties	self,
		const char *	name
	)

Get a string value by name.

Do not free the returned string. It's lifetime is controlled by the property and this properties object.

Parameters:

self	a properties list
name	the property to get

Returns:: the property's string value or NULL if it does not exist

void * mlt_properties_get_data	(	mlt_properties	self,
		const char *	name,
		int *	length
	)

Get a binary data value associated to the name.

Do not free the returned pointer if you supplied a destructor function when you set this property.

Parameters:

	self	a properties list
	name	the property to get
[out]	length	The size of the binary data in bytes, if available (often it is not, you should know)

void * mlt_properties_get_data_at	(	mlt_properties	self,
		int	index,
		int *	size
	)

Get a data value by index.

Do not free the returned pointer if you supplied a destructor function when you set this property.

Parameters:

	self	a properties list
	index	the numeric index of the property
[out]	size	the size of the binary data in bytes or NULL if the index is out of range

double mlt_properties_get_double	(	mlt_properties	self,
		const char *	name
	)

Get a floating point value associated to the name.

Parameters:

self	a properties list
name	the property to get

Returns:: the floating point, 0 if not found (which may also be a legitimate value)

int mlt_properties_get_int	(	mlt_properties	self,
		const char *	name
	)

Get an integer associated to the name.

Parameters:

self	a properties list
name	the property to get

Returns:: The integer value, 0 if not found (which may also be a legitimate value)

int64_t mlt_properties_get_int64	(	mlt_properties	self,
		const char *	name
	)

Get a 64-bit integer associated to the name.

Parameters:

self	a properties list
name	the property to get

Returns:: the integer value, 0 if not found (which may also be a legitimate value)

const char * mlt_properties_get_lcnumeric ( mlt_properties self )

Get the numeric locale for this properties object.

Do not free the result.

Parameters:

self	a properties list

Returns:: the locale name if this properties has a specific locale it is using, NULL otherwise

char * mlt_properties_get_name	(	mlt_properties	self,
		int	index
	)

Get a property name by index.

Do not free the returned string.

Parameters:

self	a properties list
index	the numeric index of the property

Returns:: the name of the property or NULL if index is out of range

mlt_position mlt_properties_get_position	(	mlt_properties	self,
		const char *	name
	)

Get a position value associated to the name.

Parameters:

self	a properties list
name	the property to get

Returns:: the position, 0 if not found (which may also be a legitimate value)

char * mlt_properties_get_value	(	mlt_properties	self,
		int	index
	)

Get a property's string value by index.

Do not free the returned string.

Parameters:

self	a properties list
index	the numeric index of the property

Returns:: the property value as a string or NULL if the index is out of range

int mlt_properties_inc_ref ( mlt_properties self )

Increment the reference count.

Parameters:

self	a properties list

Returns:: the new reference count

int mlt_properties_inherit	(	mlt_properties	self,
		mlt_properties	that
	)

Copy all serializable properties to another properties list.

Parameters:

self	The properties to copy to
that	The properties to copy from

Returns:: false

int mlt_properties_init	(	mlt_properties	self,
		void *	child
	)

Initialize a properties object that was already allocated.

This does allocate its property_list, and it adds a reference count.

Parameters:

self	the properties structure to initialize
child	an opaque pointer to a subclass object

Returns:: true if failed

int mlt_properties_is_sequence ( mlt_properties properties )

Determine if the properties list is really just a sequence or ordered list.

Parameters:

properties a properties list

Returns:: true if all of the property names are numeric (a sequence)

mlt_properties mlt_properties_load ( const char * filename )

Create a properties object by reading a .properties text file.

Free the properties object with mlt_properties_close().

Deprecated:: Please start using mlt_properties_parse_yaml().

Parameters:

filename the absolute file name

Returns:: a new properties object

void mlt_properties_lock ( mlt_properties self )

Protect a properties list against concurrent access.

Parameters:

self	a properties list

void mlt_properties_mirror	(	mlt_properties	self,
		mlt_properties	that
	)

Set a properties list to be a mirror copy of another.

Note that this does not copy all existing properties. Rather, you must call this before setting the properties that you wish to copy.

Parameters:

that	the properties which will receive copies of the properties as they are set.
self	the properties to mirror

mlt_properties mlt_properties_new ( )

Create a properties object.

This allocates the properties structure and calls mlt_properties_init() on it. Free the properties object with mlt_properties_close().

Returns:: a new properties object

int mlt_properties_parse	(	mlt_properties	self,
		const char *	namevalue
	)

Set a value by parsing a name=value string.

Parameters:

self	a properties list
namevalue	a string containing name and value delimited by '='

Returns:: true if there was an error

mlt_properties mlt_properties_parse_yaml ( const char * filename )

Parse a YAML Tiny file by name.

Parameters:

filename the name of a text file containing YAML Tiny

Returns:: a new properties list

int mlt_properties_pass	(	mlt_properties	self,
		mlt_properties	that,
		const char *	prefix
	)

Pass all serializable properties that match a prefix to another properties object.

Parameters:

self	the properties to copy to
that	The properties to copy from
prefix	the property names to match (required)

Returns:: false

int mlt_properties_pass_list	(	mlt_properties	self,
		mlt_properties	that,
		const char *	list
	)

Copy all properties specified in a comma-separated list to another properties list.

White space is also a delimiter.

Author:: Zach <zachary.drew@gmail.com>

Parameters:

self	the properties to copy to
that	the properties to copy from
list	a delimited list of property names

Returns:: false

void mlt_properties_pass_property	(	mlt_properties	self,
		mlt_properties	that,
		const char *	name
	)

Copy a property to another properties list.

Author:: Zach <zachary.drew@gmail.com>

Parameters:

self	the properties to copy to
that	the properties to copy from
name	the name of the property to copy

int mlt_properties_preset	(	mlt_properties	self,
		const char *	name
	)

Set properties from a preset.

Presets are typically installed to $prefix/share/mlt/presets/{type}/{service}/[{profile}/]{name}. For example, "/usr/share/mlt/presets/consumer/avformat/dv_ntsc_wide/DVD" could be an encoding preset for a widescreen NTSC DVD Video. Do not specify the type and service in the preset name parameter; these are inferred automatically from the service to which you are applying the preset. Using the example above and assuming you are calling this function on the avformat consumer, the name passed to the function should simply be DVD. Note that the profile portion of the path is optional, but a profile-specific preset with the same name as a more generic one is given a higher priority.

Todo:: Look in a user-specific location - somewhere in the home directory.

Parameters:

self	a properties list
name	the name of a preset in a well-known location or the explicit path

Returns:: true if error

int mlt_properties_ref_count ( mlt_properties self )

Get the reference count.

Parameters:

self	a properties list

Returns:: the current reference count

int mlt_properties_rename	(	mlt_properties	self,
		const char *	source,
		const char *	dest
	)

Rename a property.

Parameters:

self	a properties list
source	the property to rename
dest	the new name

Returns:: true if the name is already in use

int mlt_properties_save	(	mlt_properties	self,
		const char *	filename
	)

Save the properties to a file by name.

This uses the dump format - one line per property.

Parameters:

self	a properties list
filename	the name of a file to create or overwrite

Returns:: true if there was an error

char * mlt_properties_serialise_yaml ( mlt_properties self )

Serialize a properties list as a string of YAML Tiny.

The caller MUST free the returned string! This operates on properties containing properties as a hierarchical data structure.

Parameters:

self	a properties list

Returns:: a string containing YAML Tiny that represents the properties list

int mlt_properties_set	(	mlt_properties	self,
		const char *	name,
		const char *	value
	)

Set a property to a string.

The property name "properties" is reserved to load the preset in value. When the value begins with '@' then it is interpreted as a very simple math expression containing only the +, -, *, and / operators. The event "property-changed" is fired after the property has been set.

This makes a copy of the string value you supply.

Parameters:

self	a properties list
name	the property to set
value	the property's new value

Returns:: true if error

int mlt_properties_set_data	(	mlt_properties	self,
		const char *	name,
		void *	value,
		int	length,
		mlt_destructor	destroy,
		mlt_serialiser	serialise
	)

Store binary data as a property.

Parameters:

self	a properties list
name	the property to set
value	an opaque pointer to binary data
length	the size of the binary data in bytes (optional)
destroy	a function to deallocate the binary data when the property is closed (optional)
serialise	a function that can serialize the binary data as text (optional)

Returns:: true if error

int mlt_properties_set_double	(	mlt_properties	self,
		const char *	name,
		double	value
	)

Set a property to a floating point value.

Parameters:

self	a properties list
name	the property to set
value	the floating point value

Returns:: true if error

int mlt_properties_set_int	(	mlt_properties	self,
		const char *	name,
		int	value
	)

Set a property to an integer value.

Parameters:

self	a properties list
name	the property to set
value	the integer

Returns:: true if error

int mlt_properties_set_int64	(	mlt_properties	self,
		const char *	name,
		int64_t	value
	)

Set a property to a 64-bit integer value.

Parameters:

self	a properties list
name	the property to set
value	the integer

Returns:: true if error

int mlt_properties_set_lcnumeric	(	mlt_properties	self,
		const char *	locale
	)

Set the numeric locale used for string/double conversions.

Parameters:

self	a properties list
locale	the locale name

Returns:: true if error

int mlt_properties_set_or_default	(	mlt_properties	self,
		const char *	name,
		const char *	value,
		const char *	def
	)

Set or default a property to a string.

This makes a copy of the string value you supply.

Parameters:

self	a properties list
name	the property to set
value	the string value to set or NULL to use the default
def	the default string if value is NULL

Returns:: true if error

int mlt_properties_set_position	(	mlt_properties	self,
		const char *	name,
		mlt_position	value
	)

Set a property to a position value.

Parameters:

self	a properties list
name	the property to get
value	the position

Returns:: true if error

void mlt_properties_unlock ( mlt_properties self )

End protecting a properties list against concurrent access.

Parameters:

self	a properties list

static void serialise_yaml	(	mlt_properties	self,
		strbuf	output,
		int	indent,
		int	is_parent_sequence
	)		`[private]`

Recursively serialize a properties list into a string buffer as YAML Tiny.

Parameters:

self	a properties list
output	a string buffer to hold the serialized YAML Tiny
indent	the number of spaces to indent (for recursion, initialize to 0)
is_parent_sequence	Is this properties list really just a sequence (for recursion, initialize to 0)?