include/mm_attrs.h

   1 /*
   2  * libmm-common
   3  *
   4  * Copyright (c) 2000 - 2011 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Contact: Jonghyuk Choi <jhchoi.choi@samsung.com>
   7  *
   8  * Licensed under the Apache License, Version 2.0 (the "License");
   9  * you may not use this file except in compliance with the License.
  10  * You may obtain a copy of the License at
  11  *
  12  * http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing, software
  15  * distributed under the License is distributed on an "AS IS" BASIS,
  16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  * See the License for the specific language governing permissions and
  18  * limitations under the License.
  19  *
  20  */
  21
  22
  23
  24 #ifndef __MM_ATTRS_H__
  25 #define __MM_ATTRS_H__
  26
  27 #include <stdarg.h>
  28 #include <mm_types.h>
  29
  30 #ifdef __cplusplus
  31         extern "C" {
  32 #endif
  33
  34
  35 /**
  36         @addtogroup COMMON
  37         @{
  38
  39         * @file mm_attrs.h
  40         * @version              1.0
  41         * @brief                This file declares data structures and functions of attribute library.
  42
  43         @par
  44         This part describes the APIs with respect to Multimedia Attribute Library.
  45         The Attribute Library is a set of attribute. An attribute contains a value,
  46         access flags and it's validation information. This document explains how to
  47         manipulate an attribute in the Attribute Library.
  48
  49  */
  50
  51 /**
  52  * Enumeration for attribute values types.
  53  */
  54 typedef enum {
  55         MM_ATTRS_TYPE_INVALID = -1,        /**< Type is invalid */
  56         MM_ATTRS_TYPE_INT,                 /**< Integer type attribute */
  57         MM_ATTRS_TYPE_DOUBLE,               /**< Double type attribute */
  58         MM_ATTRS_TYPE_STRING,              /**< UTF-8 String type attribute */
  59         MM_ATTRS_TYPE_DATA,                /**< Pointer type attribute */
  60         MM_ATTRS_TYPE_NUM,                 /**< Number of attribute type */
  61 } MMAttrsType;
  62
  63 /**
  64  * Enumeration for attribute validation type.
  65  */
  66 typedef enum {
  67         MM_ATTRS_VALID_TYPE_INVALID = -1,        /**< Invalid validation type */
  68         MM_ATTRS_VALID_TYPE_NONE,                /**< Do not check validity */
  69         MM_ATTRS_VALID_TYPE_INT_ARRAY,           /**< validity checking type of integer array */
  70         MM_ATTRS_VALID_TYPE_INT_RANGE,           /**< validity checking type of integer range */
  71         MM_ATTRS_VALID_TYPE_DOUBLE_ARRAY,           /**< validity checking type of double array */
  72         MM_ATTRS_VALID_TYPE_DOUBLE_RANGE,           /**< validity checking type of double range */
  73 } MMAttrsValidType;
  74
  75 /**
  76  * Enumeration for attribute access flag.
  77  */
  78 typedef enum {
  79         MM_ATTRS_FLAG_NONE = 0,                 /**< None flag is set */
  80         MM_ATTRS_FLAG_READABLE = 1 << 0,        /**< Readable */
  81         MM_ATTRS_FLAG_WRITABLE = 1 << 1,        /**< Writable */
  82         MM_ATTRS_FLAG_MODIFIED = 1 << 2,         /**< Modified */
  83
  84         MM_ATTRS_FLAG_RW = MM_ATTRS_FLAG_READABLE | MM_ATTRS_FLAG_WRITABLE,     /**< Readable and Writable */
  85 } MMAttrsFlag;
  86
  87
  88 /**
  89  * Validity structure
  90  */
  91 typedef struct {
  92         MMAttrsType type;
  93         MMAttrsFlag flag;
  94         MMAttrsValidType validity_type;
  95
  96         /**
  97          * a union that describes validity of the attribute.
  98          * Only when type is 'MM_ATTRS_TYPE_INT' or 'MM_ATTRS_TYPE_DOUBLE',
  99          * the attribute can have validity.
 100          */
 101         union {
 102                 /**
 103                  * Validity structure for integer array.
 104                  */
 105                 struct {
 106                         int *array;     /**< a pointer of array */
 107                         int count;      /**< size of array */
 108                         int dval;       /**< default value */
 109                 } int_array;
 110
 111                 /**
 112                  * Validity structure for integer range.
 113                  */
 114                 struct {
 115                         int min;        /**< minimum range */
 116                         int max;        /**< maximum range */
 117                         int dval;       /**< default value */
 118                 } int_range;
 119
 120                 /**
 121                  * Validity structure for double array.
 122                  */
 123                 struct {
 124                         double *array;  /**< a pointer of array */
 125                         int count;      /**< size of array */
 126                         double dval;    /**< default value */
 127                 } double_array;
 128
 129                 /**
 130                  * Validity structure for double range.
 131                  */
 132                 struct {
 133                         double min;     /**< minimum range */
 134                         double max;     /**< maximum range */
 135                         double dval;    /**< default value */
 136                 } double_range;
 137         };
 138 } MMAttrsInfo;
 139
 140
 141 #if     __GNUC__ >= 4
 142 #define __NULL_TERMINATED __attribute__((__sentinel__))
 143 #else
 144 #define __NULL_TERMINATED
 145 #endif
 146
 147 /**
 148  * This function is to set the integer value to the attribute by name.
 149  *
 150  * @param       attrs           [in] MMAttrs handle
 151  * @param       attr_name       [in] attribute name
 152  * @param       val                     [in] integer value to set
 153  *
 154  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 155  */
 156 int mm_attrs_set_int_by_name(MMHandleType attrs, const char *attr_name, int val);
 157
 158
 159 /**
 160  * This function is to get the number of attribute in the MMAttrs.
 161  *
 162  * @param       attrs           [in]    Handle of attributes list
 163  * @param       size            [out]   Number of attributes
 164  *
 165  * @return      This function returns the number of attributes in the attribute list.
 166  */
 167 int mm_attrs_get_size(MMHandleType attrs, int *size);
 168
 169
 170 /**
 171  * This function is to get the name of attribute at the given index.
 172  *
 173  * @param       attrs           [in]    Handle of attributes list
 174  * @param       index           [in]    Index of the attribute
 175  * @param       name            [out]   Name of attribute
 176  *
 177  * @return      This function returns the name of attribute on success, or NULL
 178  *                      on failure.
 179  */
 180 int mm_attrs_get_name(MMHandleType attrs, int index, char **name);
 181
 182
 183 /**
 184  * This function is to get the index of attribute at the given name.
 185  *
 186  * @param       attrs           [in]    Handle of attributes list
 187  * @param       attr_name       [in]    Name of attribute
 188  * @param       index           [out]   Index of attribute
 189  *
 190  * @return      This function returns the index of the attribute on success,
 191  *                      or negative value on failure.
 192  */
 193 int mm_attrs_get_index(MMHandleType attrs, const char *attr_name, int *index);
 194
 195
 196 /**
 197  * This function is to get the integer value from the attribute by name.
 198  *
 199  * @param       attrs           [in]    Handle of attributes list
 200  * @param       attr_name       [in]    Name of attribute
 201  * @param       val                     [out]   Value of attribute
 202  *
 203  * @return      This function returns attribute value
 204  */
 205 int mm_attrs_get_int_by_name(MMHandleType attrs, const char *attr_name, int *val);
 206
 207
 208 /**
 209  * This function is to set the string to attribute by name.
 210  *
 211  * @param       attrs           [in] MMAttrs handle
 212  * @param       attr_name       [in] attribute name
 213  * @param       string          [in] string value to set
 214  *
 215  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 216  */
 217 int mm_attrs_set_string_by_name(MMHandleType attrs, const char *attr_name, const char *string);
 218
 219
 220 /**
 221  * This function is to get the string from the attribute by name.
 222  *
 223  * @param       attrs           [in]    Handle of attributes list
 224  * @param       attr_name       [in]    Name of attribute
 225  * @param       val                     [out]   Value of attribute
 226  *
 227  * @return      This function returns the string value of attribute on success,
 228  *                      or NULL on failure
 229  */
 230 int mm_attrs_get_string_by_name(MMHandleType attrs, const char *attr_name, char **val);
 231
 232
 233 /**
 234  * This function is to set the data to the attribute by name.
 235  *
 236  * @param       attrs           [in] MMAttrs handle
 237  * @param       attr_name       [in] attribute name
 238  * @param       data            [in] data pointer to set
 239  * @param       size            [in] data size to set
 240  *
 241  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 242  */
 243 int mm_attrs_set_data_by_name(MMHandleType attrs, const char *attr_name, void *data, int size);
 244
 245 /**
 246  * This function is to get the data from the attribute by name.
 247  *
 248  * @param       attrs           [in]    Handle of attributes list
 249  * @param       attr_name       [in]    Name of attribute
 250  * @param       data            [out] data pointer to set
 251  *
 252  * @return      This function returns user defined value on success, or NULL
 253  *                      on failure
 254  */
 255 int mm_attrs_get_data_by_name(MMHandleType attrs, const char *attr_name, void **data);
 256
 257
 258 /**
 259  * This function is to retrieve type of attribute.
 260  *
 261  * @param       attrs           [in] List of attributes
 262  * @param       index           [in] Index of attribute
 263  * @param       attrtype        [out] On return contains type of attribute
 264  *
 265  * @return      This function returns MM_ERROR_NONE.
 266  * @see         MMAttrsType
 267  */
 268 int mm_attrs_get_type(MMHandleType attrs, int index, MMAttrsType *attrtype);
 269
 270
 271 /**
 272  * This function is to get flags of attribute with given index.
 273  *
 274  * @param       attrs   [in] List of attributes
 275  * @param       index   [in] Index of attribute
 276  * @param       flags   [out] On return contains flags of attribute.
 277  *
 278  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 279  * @see         MMAttrsFlag
 280  */
 281 int mm_attrs_get_flags(MMHandleType attrs, int index, int *flags);
 282
 283
 284 /**
 285  * This function is to get valid value type of attribute with given index.
 286  *
 287  * @param       attrs   [in] List of attributes
 288  * @param       index   [in] Index of attribute
 289  * @param       type    [out] On return contains valid value type of attribute
 290  *
 291  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 292  * @see         MMAttrsType
 293  */
 294 int mm_attrs_get_valid_type(MMHandleType attrs, int index, int *type);
 295
 296
 297 /**
 298  * This function is to get valid range of attribute with given index.
 299  *
 300  * @param       attrs   [in] List of attributes
 301  * @param       index   [in] Index of attribute
 302  * @param       min             [out] minimum value of the valid range
 303  * @param       max             [out] maximum value of the valid range
 304  *
 305  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 306  */
 307 int mm_attrs_get_valid_range(MMHandleType attrs, int index, int *min, int *max);
 308
 309
 310 /**
 311  * This function is to get valid array of attribute with given index.
 312  *
 313  * @param       attrs   [in] list of attributes
 314  * @param       index   [in] Index of attribute
 315  * @param       count   [out] number of array
 316  * @param       array   [out] on return contains valid array of attribute
 317  *
 318  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 319  */
 320 int mm_attrs_get_valid_array(MMHandleType attrs, int index, int *count,  int **array);
 321
 322
 323 /**
 324  * This function is to set integer value to attribute with given index.
 325  *
 326  * @param       attrs   [in] List of attributes
 327  * @param       index   [in] Index of attribute
 328  * @param       val             [in] integer value to set
 329  *
 330  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 331  * @see         mm_attrs_get_int
 332  */
 333 int mm_attrs_set_int(MMHandleType attrs, int index, int val);
 334
 335
 336 /**
 337  * This function is to get integer value to attribute with given index.
 338  *
 339  * @param       attrs   [in] List of attributes
 340  * @param       index   [in] Index of attribute
 341  * @param       val             [out] On return contains integer value of attribute
 342  *
 343  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 344  * @remarks     If type of attributes is not an integer type, the value which is returned by this function is meaningless.
 345  * @see         mm_attrs_get_int
 346  */
 347 int mm_attrs_get_int(MMHandleType attrs, int index,  int *val);
 348
 349
 350 /**
 351  * This function is to set double value to attribute with given index.
 352  *
 353  * @param       attrs   [in]    List of attributes
 354  * @param       index   [in]    Index of attribute
 355  * @param       val             [in]    Integer value to set
 356  *
 357  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 358  * @see         mm_attrs_get_double
 359  */
 360 int mm_attrs_set_double(MMHandleType attrs, int index, double val);
 361
 362
 363 /**
 364  * This function is to set the double value to the attribute by name.
 365  *
 366  * @param       attrs           [in]    Handle of attributes list
 367  * @param       attr_name       [in]    Name of attribute
 368  * @param       val                     [in]    Integer value to set
 369  *
 370  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 371  */
 372 int mm_attrs_set_double_by_name(MMHandleType attrs, const char *attr_name, double val);
 373
 374
 375 /**
 376  * This function is to get double value to attribute with given index.
 377  *
 378  * @param       attrs           [in]    List of attributes
 379  * @param       index           [in]    Index of attribute
 380  * @param       attrval         [out]   On return contains double value of attribute on success, or invalid value.
 381  *
 382  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 383  * @see         mm_attrs_set_double
 384  */
 385 int mm_attrs_get_double(MMHandleType attrs, int index, double *attrval);
 386
 387
 388 /**
 389  * This function is to get the double value from the attribute by name.
 390  *
 391  * @param       attrs           [in]    Handle of attributes list
 392  * @param       attr_name       [in]    Name of attribute
 393  * @param       val                     [out]   Double value to set
 394  *
 395  * @return      This function returns attribute value
 396  */
 397 int mm_attrs_get_double_by_name(MMHandleType attrs, const char *attr_name, double *val);
 398
 399
 400 /**
 401  * This function is to set string to attribute with given index.
 402  *
 403  * @param       attrs           [in] List of attributes
 404  * @param       index           [in] Index of attribute
 405  * @param       string          [in] String to set
 406  * @param       size            [in] length of string to set
 407  *
 408  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 409  * @see         mm_attrs_get_string
 410  */
 411 int mm_attrs_set_string(MMHandleType attrs, int index, const char *string, int size);
 412
 413
 414 /**
 415  * This function is to get string to attribute with given index.
 416  *
 417  * @param       attrs           [in] List of attributes
 418  * @param       index           [in] Index of attribute
 419  * @param       sval            [in] Placeholder to output string buffer
 420  * @param       size            [in] The field contains number of characters filled in the buffer
 421  *
 422  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 423  * @remarks     Application would be responsible for managing/releasing the string
 424  * @see         mm_attrs_set_string
 425  */
 426 int mm_attrs_get_string(MMHandleType attrs, int index, char **sval, int *size);
 427
 428
 429 /**
 430  * This function is to set pointer to attribute with given index.
 431  *
 432  * @param       attrs           [in] List of attributes
 433  * @param       index           [in] Index of attribute
 434  * @param       data            [in] data to set
 435  * @param       size            [in] Length of input data
 436  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 437  *
 438  * @remarks     Data type is the reference to memory which is allocated by user. The allocated memory must be freed by user.
 439  * @see         mm_attrs_get_data
 440  */
 441 int mm_attrs_set_data(MMHandleType attrs, int index, void *data,  int size);
 442
 443 /**
 444  * This function is to get pointer to attribute with given index.
 445  *
 446  * @param       attrs           [in] List of attributes
 447  * @param       index           [in] Index of attribute
 448  * @param       data            [out] Placeholder to output data buffer
 449  * @param       size            [out] The field contains number of bytes filled in the buffer
 450  *
 451  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 452  * @remarks     Application would be responsible for managing/releasing data
 453  * @see         mm_attrs_set_data
 454  */
 455 int mm_attrs_get_data(MMHandleType attrs, int index, void **data, int *size);
 456
 457
 458 /**
 459  * A function to get  information of the attribute
 460  *
 461  * @param       attrs           [in]    List of attributes
 462  * @param       index           [in]    Index of attribute
 463  * @param       info            [out]   Information of the attribute
 464  *
 465  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 466  */
 467 int mm_attrs_get_info(MMHandleType attrs, int index, MMAttrsInfo *info);
 468
 469
 470 /**
 471  * This function is to get array of attribute with given name.
 472  *
 473  * @param       attrs           [in]    List of attributes
 474  * @param       attr_name       [in]    Name of attribute
 475  * @param       info            [out]   Information of the attribute
 476  *
 477  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 478  */
 479 int mm_attrs_get_info_by_name(MMHandleType attrs, const char *attr_name, MMAttrsInfo *info);
 480
 481 /**
 482  * Sets properties on an object.
 483  *
 484  * @param       attrs                           [in]    List of attributes
 485  * @param       err_attr_name           [out]   the name of attributes that occurs error. Free this variable after use.
 486  * @param       attribute_name          [in]    name of the first property to set
 487  * @param       ...                                     [in]    value for the first property, followed optionally by more
 488  *  name/value pairs, followed by %NULL
 489  *
 490  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 491  * @remarks     Multiple setter of attribute
 492  * @see         mm_attrs_set_int, mm_attrs_set_string, ...
 493  */
 494 int mm_attrs_multiple_set(MMHandleType attrs,  char **err_attr_name, const char *attribute_name, ...) __NULL_TERMINATED;
 495
 496
 497 /**
 498  * Gets properties on an object.
 499  *
 500  * @param       attrs                           [in]    List of attributes
 501  * @param       err_attr_name           [out]   the name of attributes that occurs error. Free this variable after use.
 502  * @param       attribute_name          [in]    name of the first property to set
 503  * @param       ...                                     [in]    value for the first property, followed optionally by more
 504  *  name/value pairs, followed by %NULL
 505  *
 506  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 507  * @remarks     Multiple setter of attribute
 508  * @see         mm_attrs_set_int, mm_attrs_set_string, ...
 509  */
 510 int mm_attrs_multiple_get(MMHandleType attrs,  char **err_attr_name, const char *attribute_name, ...) __NULL_TERMINATED;
 511
 512
 513 /**
 514  * Sets properties on an object with va_list param.
 515  *
 516  * @param       attrs                                   [in]    List of attributes
 517  * @param       err_attr_name                   [out]   the name of attributes that occurs error. Free this variable after use.
 518  * @param       attribute_name                  [in]    name of the first property to set
 519  * @param       var_args                                [in]    variable arguments
 520  *
 521  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 522  * @remarks     Multiple setter of attribute
 523  * @see         mm_attrs_multiple_set
 524  */
 525 int mm_attrs_set_valist(MMHandleType attrs, char **err_attr_name, const char *attribute_name, va_list var_args);
 526
 527
 528 /**
 529  * Gets properties on an object with va_list param.
 530  *
 531  * @param       attrs                                   [in]    List of attributes
 532  * @param       err_attr_name                   [out]   the name of attributes that occurs error. Free this variable after use.
 533  * @param       attribute_name                  [in]    name of the first property to set
 534  * @param       var_args                                [in]    variable arguments
 535  *
 536  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 537  * @remarks     Multiple setter of attribute
 538  * @see         mm_attrs_multiple_get
 539  */
 540 int mm_attrs_get_valist(MMHandleType attrs, char **err_attr_name, const char *attribute_name, va_list var_args);
 541
 542 /**
 543  * @}
 544  */
 545
 546 #ifdef __cplusplus
 547         }
 548 #endif
 549
 550 #endif /* __MM_ATTRS_H__ */