3 * \brief Property class definition
6 * Copyright (C) 2003-2009 Ushodaya Enterprises Limited
7 * \author Charles Yates <charles.yates@pandora.be>
9 * This library is free software; you can redistribute it and/or
10 * modify it under the terms of the GNU Lesser General Public
11 * License as published by the Free Software Foundation; either
12 * version 2.1 of the License, or (at your option) any later version.
14 * This library is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 * Lesser General Public License for more details.
19 * You should have received a copy of the GNU Lesser General Public
20 * License along with this library; if not, write to the Free Software
21 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
24 #include "mlt_property.h"
31 /** Bit pattern used internally to indicated representations available.
36 mlt_prop_none = 0, //!< not set
37 mlt_prop_int = 1, //!< set as an integer
38 mlt_prop_string = 2, //!< set as string or already converted to string
39 mlt_prop_position = 4,//!< set as a position
40 mlt_prop_double = 8, //!< set as a floating point
41 mlt_prop_data = 16, //!< set as opaque binary
42 mlt_prop_int64 = 32 //!< set as a 64-bit integer
46 /** \brief Property class
48 * A property is like a variant or dynamic type. They are used for many things
49 * in MLT, but in particular they are the parameter mechanism for the plugins.
54 /// Stores a bit pattern of types available for this property
55 mlt_property_type types;
57 /// Atomic type handling
59 mlt_position prop_position;
66 /// Generic type handling
69 mlt_destructor destructor;
70 mlt_serialiser serialiser;
73 /** Construct a property and initialize it
74 * \public \memberof mlt_property_s
77 mlt_property mlt_property_init( )
79 mlt_property this = malloc( sizeof( struct mlt_property_s ) );
84 this->prop_position = 0;
85 this->prop_double = 0;
87 this->prop_string = NULL;
90 this->destructor = NULL;
91 this->serialiser = NULL;
96 /** Clear (0/null) a property.
98 * Frees up any associated resources in the process.
99 * \private \memberof mlt_property_s
100 * \param this a property
103 static inline void mlt_property_clear( mlt_property this )
105 // Special case data handling
106 if ( this->types & mlt_prop_data && this->destructor != NULL )
107 this->destructor( this->data );
109 // Special case string handling
110 if ( this->types & mlt_prop_string )
111 free( this->prop_string );
116 this->prop_position = 0;
117 this->prop_double = 0;
118 this->prop_int64 = 0;
119 this->prop_string = NULL;
122 this->destructor = NULL;
123 this->serialiser = NULL;
126 /** Set the property to an integer value.
128 * \public \memberof mlt_property_s
129 * \param this a property
130 * \param value an integer
134 int mlt_property_set_int( mlt_property this, int value )
136 mlt_property_clear( this );
137 this->types = mlt_prop_int;
138 this->prop_int = value;
142 /** Set the property to a floating point value.
144 * \public \memberof mlt_property_s
145 * \param this a property
146 * \param value a double precision floating point value
150 int mlt_property_set_double( mlt_property this, double value )
152 mlt_property_clear( this );
153 this->types = mlt_prop_double;
154 this->prop_double = value;
158 /** Set the property to a position value.
160 * Position is a relative time value in frame units.
161 * \public \memberof mlt_property_s
162 * \param this a property
163 * \param value a position value
167 int mlt_property_set_position( mlt_property this, mlt_position value )
169 mlt_property_clear( this );
170 this->types = mlt_prop_position;
171 this->prop_position = value;
175 /** Set the property to a string value.
177 * This makes a copy of the string you supply so you do not need to track
178 * a new reference to it.
179 * \public \memberof mlt_property_s
180 * \param this a property
181 * \param value the string to copy to the property
182 * \return true if it failed
185 int mlt_property_set_string( mlt_property this, const char *value )
187 if ( value != this->prop_string )
189 mlt_property_clear( this );
190 this->types = mlt_prop_string;
192 this->prop_string = strdup( value );
196 this->types = mlt_prop_string;
198 return this->prop_string == NULL;
201 /** Set the property to a 64-bit integer value.
203 * \public \memberof mlt_property_s
204 * \param this a property
205 * \param value a 64-bit integer
209 int mlt_property_set_int64( mlt_property this, int64_t value )
211 mlt_property_clear( this );
212 this->types = mlt_prop_int64;
213 this->prop_int64 = value;
217 /** Set a property to an opaque binary value.
219 * This does not make a copy of the data. You can use a Properties object
220 * with its reference tracking and the destructor function to control
221 * the lifetime of the data. Otherwise, pass NULL for the destructor
222 * function and control the lifetime yourself.
223 * \public \memberof mlt_property_s
224 * \param this a property
225 * \param value an opaque pointer
226 * \param length the number of bytes pointed to by value (optional)
227 * \param destructor a function to use to destroy this binary data (optional, assuming you manage the resource)
228 * \param serialiser a function to use to convert this binary data to a string (optional)
232 int mlt_property_set_data( mlt_property this, void *value, int length, mlt_destructor destructor, mlt_serialiser serialiser )
234 if ( this->data == value )
235 this->destructor = NULL;
236 mlt_property_clear( this );
237 this->types = mlt_prop_data;
239 this->length = length;
240 this->destructor = destructor;
241 this->serialiser = serialiser;
245 /** Convert a base 10 or base 16 string to an integer.
247 * The string must begin with '0x' to be interpreted as hexadecimal.
248 * Otherwise, it is interpreted as base 10.
249 * If the string begins with '#' it is interpreted as a hexadecimal color value
250 * in the form RRGGBB or AARRGGBB. Color values that begin with '0x' are
251 * always in the form RRGGBBAA where the alpha components are not optional.
252 * Applications and services should expect the binary color value in bytes to
253 * be in the following order: RGBA. This means they will have to cast the int
254 * to an unsigned int. This is especially important when they need to shift
255 * right to obtain RGB without alpha in order to make it do a logical instead
256 * of arithmetic shift.
258 * \private \memberof mlt_property_s
259 * \param value a string to convert
260 * \return the resultant integer
262 static inline int mlt_property_atoi( const char *value )
266 // Parse a hex color value as #RRGGBB or #AARRGGBB.
267 if ( value[0] == '#' )
269 unsigned int rgb = strtoul( value + 1, NULL, 16 );
270 unsigned int alpha = ( strlen( value ) > 7 ) ? ( rgb >> 24 ) : 0xff;
271 return ( rgb << 8 ) | alpha;
273 // Do hex and decimal explicitly to avoid decimal value with leading zeros
274 // interpreted as octal.
275 else if ( value[0] == '0' && value[1] == 'x' )
277 return strtoul( value + 2, NULL, 16 );
281 return strtol( value, NULL, 10 );
285 /** Get the property as an integer.
287 * \public \memberof mlt_property_s
288 * \param this a property
289 * \return an integer value
292 int mlt_property_get_int( mlt_property this )
294 if ( this->types & mlt_prop_int )
295 return this->prop_int;
296 else if ( this->types & mlt_prop_double )
297 return ( int )this->prop_double;
298 else if ( this->types & mlt_prop_position )
299 return ( int )this->prop_position;
300 else if ( this->types & mlt_prop_int64 )
301 return ( int )this->prop_int64;
302 else if ( this->types & mlt_prop_string )
303 return mlt_property_atoi( this->prop_string );
307 /** Get the property as a floating point.
309 * \public \memberof mlt_property_s
310 * \param this a property
311 * \return a floating point value
314 double mlt_property_get_double( mlt_property this )
316 if ( this->types & mlt_prop_double )
317 return this->prop_double;
318 else if ( this->types & mlt_prop_int )
319 return ( double )this->prop_int;
320 else if ( this->types & mlt_prop_position )
321 return ( double )this->prop_position;
322 else if ( this->types & mlt_prop_int64 )
323 return ( double )this->prop_int64;
324 else if ( this->types & mlt_prop_string )
325 return atof( this->prop_string );
329 /** Get the property as a position.
331 * A position is an offset time in terms of frame units.
332 * \public \memberof mlt_property_s
333 * \param this a property
334 * \return the position in frames
337 mlt_position mlt_property_get_position( mlt_property this )
339 if ( this->types & mlt_prop_position )
340 return this->prop_position;
341 else if ( this->types & mlt_prop_int )
342 return ( mlt_position )this->prop_int;
343 else if ( this->types & mlt_prop_double )
344 return ( mlt_position )this->prop_double;
345 else if ( this->types & mlt_prop_int64 )
346 return ( mlt_position )this->prop_int64;
347 else if ( this->types & mlt_prop_string )
348 return ( mlt_position )atol( this->prop_string );
352 /** Convert a string to a 64-bit integer.
354 * If the string begins with '0x' it is interpreted as a hexadecimal value.
355 * \private \memberof mlt_property_s
356 * \param value a string
357 * \return a 64-bit integer
360 static inline int64_t mlt_property_atoll( const char *value )
364 else if ( value[0] == '0' && value[1] == 'x' )
365 return strtoll( value + 2, NULL, 16 );
367 return strtoll( value, NULL, 10 );
370 /** Get the property as a signed integer.
372 * \public \memberof mlt_property_s
373 * \param this a property
374 * \return a 64-bit integer
377 int64_t mlt_property_get_int64( mlt_property this )
379 if ( this->types & mlt_prop_int64 )
380 return this->prop_int64;
381 else if ( this->types & mlt_prop_int )
382 return ( int64_t )this->prop_int;
383 else if ( this->types & mlt_prop_double )
384 return ( int64_t )this->prop_double;
385 else if ( this->types & mlt_prop_position )
386 return ( int64_t )this->prop_position;
387 else if ( this->types & mlt_prop_string )
388 return mlt_property_atoll( this->prop_string );
392 /** Get the property as a string.
394 * The caller is not responsible for deallocating the returned string!
395 * The string is deallocated when the Property is closed.
396 * This tries its hardest to convert the property to string including using
397 * a serialization function for binary data, if supplied.
398 * \public \memberof mlt_property_s
399 * \param this a property
400 * \return a string representation of the property or NULL if failed
403 char *mlt_property_get_string( mlt_property this )
405 // Construct a string if need be
406 if ( ! ( this->types & mlt_prop_string ) )
408 if ( this->types & mlt_prop_int )
410 this->types |= mlt_prop_string;
411 this->prop_string = malloc( 32 );
412 sprintf( this->prop_string, "%d", this->prop_int );
414 else if ( this->types & mlt_prop_double )
416 this->types |= mlt_prop_string;
417 this->prop_string = malloc( 32 );
418 sprintf( this->prop_string, "%f", this->prop_double );
420 else if ( this->types & mlt_prop_position )
422 this->types |= mlt_prop_string;
423 this->prop_string = malloc( 32 );
424 sprintf( this->prop_string, "%d", (int)this->prop_position ); /* I don't know if this is wanted. -Zach */
426 else if ( this->types & mlt_prop_int64 )
428 this->types |= mlt_prop_string;
429 this->prop_string = malloc( 32 );
430 sprintf( this->prop_string, "%lld", (long long int)this->prop_int64 );
432 else if ( this->types & mlt_prop_data && this->serialiser != NULL )
434 this->types |= mlt_prop_string;
435 this->prop_string = this->serialiser( this->data, this->length );
439 // Return the string (may be NULL)
440 return this->prop_string;
443 /** Get the binary data from a property.
445 * This only works if you previously put binary data into the property.
446 * This does not return a copy of the data; it returns a pointer to it.
447 * If you supplied a destructor function when setting the binary data,
448 * the destructor is used when the Property is closed to free the memory.
449 * Therefore, only free the returned pointer if you did not supply a
450 * destructor function.
451 * \public \memberof mlt_property_s
452 * \param this a property
453 * \param[out] length the size of the binary object in bytes (optional)
454 * \return an opaque data pointer or NULL if not available
457 void *mlt_property_get_data( mlt_property this, int *length )
459 // Assign length if not NULL
460 if ( length != NULL )
461 *length = this->length;
463 // Return the data (note: there is no conversion here)
467 /** Destroy a property and free all related resources.
469 * \public \memberof mlt_property_s
470 * \param this a property
473 void mlt_property_close( mlt_property this )
475 mlt_property_clear( this );
481 * A Property holding binary data only copies the data if a serialiser
482 * function was supplied when you set the Property.
483 * \public \memberof mlt_property_s
484 * \author Zach <zachary.drew@gmail.com>
485 * \param this a property
486 * \param that another property
488 void mlt_property_pass( mlt_property this, mlt_property that )
490 mlt_property_clear( this );
492 this->types = that->types;
494 if ( this->types & mlt_prop_int64 )
495 this->prop_int64 = that->prop_int64;
496 else if ( this->types & mlt_prop_int )
497 this->prop_int = that->prop_int;
498 else if ( this->types & mlt_prop_double )
499 this->prop_double = that->prop_double;
500 else if ( this->types & mlt_prop_position )
501 this->prop_position = that->prop_position;
502 else if ( this->types & mlt_prop_string )
504 if ( that->prop_string != NULL )
505 this->prop_string = strdup( that->prop_string );
507 else if ( this->types & mlt_prop_data && this->serialiser != NULL )
509 this->types = mlt_prop_string;
510 this->prop_string = this->serialiser( this->data, this->length );