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_ARRAY,               /**< Array type attribute */
  61         MM_ATTRS_TYPE_RANGE,               /**< Range type attribute */
  62         MM_ATTRS_TYPE_NUM,                 /**< Number of attribute type */
  63 }MMAttrsType;
  64
  65 /**
  66  * Enumeration for attribute validation type.
  67  */
  68 typedef enum {
  69         MM_ATTRS_VALID_TYPE_INVALID = -1,        /**< Invalid validation type */
  70         MM_ATTRS_VALID_TYPE_NONE,                /**< Do not check validity */
  71         MM_ATTRS_VALID_TYPE_INT_ARRAY,           /**< validity checking type of integer array */
  72         MM_ATTRS_VALID_TYPE_INT_RANGE,           /**< validity checking type of integer range */
  73         MM_ATTRS_VALID_TYPE_DOUBLE_ARRAY,           /**< validity checking type of double array */
  74         MM_ATTRS_VALID_TYPE_DOUBLE_RANGE,           /**< validity checking type of double range */
  75 } MMAttrsValidType;
  76
  77 /**
  78  * Enumeration for attribute access flag.
  79  */
  80 typedef enum {
  81         MM_ATTRS_FLAG_NONE = 0,                 /**< None flag is set */
  82         MM_ATTRS_FLAG_READABLE = 1 << 0,        /**< Readable */
  83         MM_ATTRS_FLAG_WRITABLE = 1 << 1,        /**< Writable */
  84         MM_ATTRS_FLAG_MODIFIED = 1 << 2,         /**< Modified */
  85
  86         MM_ATTRS_FLAG_RW = MM_ATTRS_FLAG_READABLE | MM_ATTRS_FLAG_WRITABLE,     /**< Readable and Writable */
  87 } MMAttrsFlag;
  88
  89
  90 /**
  91  * Validity structure
  92  */
  93 typedef struct {
  94         MMAttrsType type;
  95         MMAttrsFlag flag;
  96         MMAttrsValidType validity_type;
  97
  98         /**
  99          * a union that describes validity of the attribute.
 100          * Only when type is 'MM_ATTRS_TYPE_INT' or 'MM_ATTRS_TYPE_DOUBLE',
 101          * the attribute can have validity.
 102          */
 103         union {
 104                 /**
 105                  * Validity structure for integer array.
 106                  */
 107                  struct {
 108                         int                             * array;                /**< a pointer of array */
 109                         int                             count;                  /**< size of array */
 110                 } int_array;
 111
 112                 /**
 113                  * Validity structure for integer range.
 114                  */
 115                 struct {
 116                         int                             min;                    /**< minimum range */
 117                         int                             max;                    /**< maximum range */
 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_array;
 127
 128                 /**
 129                  * Validity structure for double range.
 130                  */
 131                 struct {
 132                         double                  min;                    /**< minimum range */
 133                         double                  max;                    /**< maximum range */
 134                 } double_range;
 135         };
 136 } MMAttrsInfo;
 137
 138
 139 #if     __GNUC__ >= 4
 140 #define __NULL_TERMINATED __attribute__((__sentinel__))
 141 #else
 142 #define __NULL_TERMINATED
 143 #endif
 144
 145 /**
 146  * This function is to set the integer value to the attribute by name.
 147  * @param       attrs           [in] MMAttrs handle
 148  * @param       attr_name       [in] attribute name
 149  * @param       val             [in] integer value to set
 150  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 151  */
 152 int mm_attrs_set_int_by_name(MMHandleType attrs, const char *attr_name, int val);
 153
 154
 155 /**
 156  * This function is to get the number of attribute in the MMAttrs.
 157  * @param       attrs           [in]    Handle of attributes list
 158  * @param       size            [out]   Number of attributes
 159  * @return      This function returns the number of attributes in the attribute list.
 160  */
 161 int mm_attrs_get_size(MMHandleType attrs, int *size);
 162
 163
 164 /**
 165  * This function is to get the name of attribute at the given index.
 166  * @param       attrs           [in]    Handle of attributes list
 167  * @param       index           [in]    Index of the attribute
 168  * @param       name            [out]   Name of attribute
 169  * @return      This function returns the name of attribute on success, or NULL
 170  *                      on failure.
 171  */
 172 int mm_attrs_get_name(MMHandleType attrs, int index, char **name);
 173
 174
 175 /**
 176  * This function is to get the index of attribute at the given name.
 177  * @param       attrs           [in]    Handle of attributes list
 178  * @param       attr_name       [in]    Name of attribute
 179  * @param       index           [out]   Index of attribute
 180  * @return      This function returns the index of the attribute on success,
 181  *                      or negative value on failure.
 182  */
 183 int mm_attrs_get_index(MMHandleType attrs, const char *attr_name, int *index);
 184
 185
 186 /**
 187  * This function is to get the integer value from the attribute by name.
 188  * @param       attrs           [in]    Handle of attributes list
 189  * @param       attr_name       [in]    Name of attribute
 190  * @param       val                     [out]   Value of attribute
 191  * @return      This function returns attribute value
 192  */
 193 int mm_attrs_get_int_by_name(MMHandleType attrs, const char *attr_name, int *val);
 194
 195
 196 /**
 197  * This function is to set the string to attribute by name.
 198  * @param       attrs           [in] MMAttrs handle
 199  * @param       attr_name       [in] attribute name
 200  * @param       string          [in] string value to set
 201  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 202  */
 203 int mm_attrs_set_string_by_name(MMHandleType attrs, const char *attr_name, const char *string);
 204
 205
 206 /**
 207  * This function is to get the string from the attribute by name.
 208  * @param       attrs           [in]    Handle of attributes list
 209  * @param       attr_name       [in]    Name of attribute
 210  * @param       val                     [out]   Value of attribute
 211  * @return      This function returns the string value of attribute on success,
 212  *                      or NULL on failure
 213  */
 214 int mm_attrs_get_string_by_name(MMHandleType attrs, const char *attr_name, char **val);
 215
 216
 217 /**
 218  * This function is to set the data to the attribute by name.
 219  * @param       attrs           [in] MMAttrs handle
 220  * @param       attr_name       [in] attribute name
 221  * @param       data            [in] data pointer to set
 222  * @param       size            [in] data size to set
 223  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 224  */
 225 int mm_attrs_set_data_by_name(MMHandleType attrs, const char *attr_name, void *data, int size);
 226
 227 /**
 228  * This function is to get the data from the attribute by name.
 229  * @param       attrs                   [in]    Handle of attributes list
 230  * @param       attr_name       [in]    Name of attribute
 231  * @param       data                    [out] data pointer to set
 232  * @return      This function returns user defined value on success, or NULL
 233  *                      on failure
 234  */
 235 int mm_attrs_get_data_by_name(MMHandleType attrs, const char *attr_name, void **data);
 236
 237
 238 /**
 239  * This function is to retrieve type of attribute.
 240  * @param       attrs           [in] List of attributes
 241  * @param       id              [in] ID of attribute
 242  * @param       attrtype        [out] On return contains type of attribute
 243  * @return      This function returns MM_ERROR_NONE.
 244  * @see         MMAttrsType
 245  */
 246 int mm_attrs_get_type(MMHandleType attrs, int id, MMAttrsType *attrtype);
 247
 248
 249 /**
 250  * This function is to get flags of attribute with given id.
 251  * @param       attrs           [in] List of attributes
 252  * @param       id              [in] ID of attribute
 253  * @param       flags           [out] On return contains flags of attribute.
 254  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 255  * @see         MMAttrsFlag
 256  */
 257 int mm_attrs_get_flags(MMHandleType attrs, int id, int *flags);
 258
 259
 260 /**
 261  * This function is to get valid value type of attribute with given id.
 262  * @param       attrs           [in] List of attributes
 263  * @param       id              [in] ID of attribute
 264  * @param       type            [out] On return contains valid value type of attribute
 265  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 266  * @see         MMAttrsType
 267  */
 268 int mm_attrs_get_valid_type(MMHandleType attrs, int id, int *type);
 269
 270
 271 /**
 272  * This function is to get valid range of attribute with given id.
 273  * @param       attrs           [in] List of attributes
 274  * @param       id              [in] ID of attribute
 275  * @param       min             [out] minimum value of the valid range.
 276  * @param       max             [out] maximum value of the valid range.
 277  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 278  */
 279 int mm_attrs_get_valid_range(MMHandleType attrs, int id, int *min, int *max);
 280
 281
 282 /**
 283  * This function is to get valid array of attribute with given id.
 284  * @param       attrs           [in] list of attributes
 285  * @param       id              [in] ID of attribute
 286  * @param       count           [out] number of array
 287  * @param       array           [out] on return contains valid array of attribute
 288  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 289  */
 290 int mm_attrs_get_valid_array(MMHandleType attrs, int id, int *count,  int **array);
 291
 292
 293 /**
 294  * This function is to get valid double type range of attribute with given id.
 295  * @param       attrs           [in] List of attributes
 296  * @param       id              [in] ID of attribute
 297  * @param       min             [out] minimum value of the valid range.
 298  * @param       max             [out] maximum value of the valid range.
 299  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 300  */
 301 int mm_attrs_get_valid_double_range(MMHandleType h, int idx, double *min, double *max);
 302
 303
 304 /**
 305  * This function is to get valid double type array of attribute with given id.
 306  * @param       attrs           [in] list of attributes
 307  * @param       id              [in] ID of attribute
 308  * @param       count           [out] number of array
 309  * @param       array           [out] on return contains valid array of attribute
 310  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 311  */
 312 int mm_attrs_get_valid_double_array(MMHandleType h, int idx, int *count,  double **array);
 313
 314
 315 /**
 316  * This function is to set integer value to attribute with given id.
 317  * @param       attrs           [in] List of attributes
 318  * @param       id              [in] ID of attribute
 319  * @param       val             [in] integer value to set
 320  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 321  * @see         mm_attrs_get_int
 322  */
 323 int mm_attrs_set_int(MMHandleType attrs, int id, int val);
 324
 325
 326 /**
 327  * This function is to get integer value to attribute with given id.
 328  * @param       attrs           [in] List of attributes
 329  * @param       id              [in] ID of attribute
 330  * @param       val             [out] On return contains integer value of attribute
 331  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 332  * @remarks     If type of attributes is not an integer type, the value which is returned by this function is meaningless.
 333  * @see         mm_attrs_get_int
 334  */
 335 int mm_attrs_get_int(MMHandleType attrs, int id,  int *val);
 336
 337
 338 /**
 339  * This function is to set double value to attribute with given id.
 340  *
 341  * @param       attrs           [in]    List of attributes
 342  * @param       id              [in]    ID of attribute
 343  * @param       val             [in]    Integer value to set
 344  *
 345  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 346  * @see         mm_attrs_get_double
 347  */
 348 int mm_attrs_set_double(MMHandleType attrs, int id, double val);
 349
 350
 351 /**
 352  * This function is to set the double value to the attribute by name.
 353  *
 354  * @param       attrs           [in]    Handle of attributes list
 355  * @param       attr_name       [in]    Name of attribute
 356  * @param       val             [in]    Integer value to set
 357  *
 358  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 359  */
 360 int mm_attrs_set_double_by_name(MMHandleType attrs, const char *attr_name, double val);
 361
 362
 363 /**
 364  * This function is to get double value to attribute with given id.
 365  *
 366  * @param       attrs           [in]    List of attributes
 367  * @param       id              [in]    ID of attribute
 368  * @param       attrval         [out]   On return contains double value of attribute on success, or invalid value.
 369  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 370  * @see         mm_attrs_set_double
 371  */
 372 int mm_attrs_get_double(MMHandleType attrs, int id, double *attrval);
 373
 374
 375 /**
 376  * This function is to get the double value from the attribute by name.
 377  *
 378  * @param       attrs           [in]    Handle of attributes list
 379  * @param       attr_name       [in]    Name of attribute
 380  * @param       val             [out]   Double value to set
 381  *
 382  * @return      This function returns attribute value
 383  */
 384 int mm_attrs_get_double_by_name(MMHandleType attrs, const char *attr_name, double *val);
 385
 386
 387 /**
 388  * This function is to set string to attribute with given id.
 389  * @param       attrs           [in] List of attributes
 390  * @param       id              [in] ID of attribute
 391  * @param       string          [in] String to set
 392  * @param       size            [in] length of string to set
 393  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 394  * @see         mm_attrs_get_string
 395  */
 396 int mm_attrs_set_string(MMHandleType attrs, int id, const char *string, int size);
 397
 398
 399 /**
 400  * This function is to get string to attribute with given id.
 401  * @param       attrs           [in] List of attributes
 402  * @param       id              [in] ID of attribute
 403  * @param       sval            [in] Placeholder to output string buffer
 404  * @param       size            [in] The field contains number of characters filled in the buffer
 405  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 406  * @remarks     Application would be responsible for managing/releasing the string
 407  * @see         mm_attrs_set_string
 408  */
 409 int mm_attrs_get_string(MMHandleType attrs, int id,char **sval, int *size);
 410
 411
 412 /**
 413  * This function is to set pointer to attribute with given id.
 414  * @param       attrs           [in] List of attributes
 415  * @param       id              [in] ID of attribute
 416  * @param       data            [in] data to set
 417  * @param       size            [in] Length of input data
 418  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 419  * @remarks     Data type is the reference to memory which is allocated by user. The allocated memory must be freed by user.
 420  * @see         mm_attrs_get_data
 421  */
 422 int mm_attrs_set_data(MMHandleType attrs, int id, void *data,  int size);
 423
 424 /**
 425  * This function is to get pointer to attribute with given id.
 426  * @param       attrs           [in] List of attributes
 427  * @param       id              [in] ID of attribute
 428  * @param       data            [out] Placeholder to output data buffer
 429  * @param       size            [out] The field contains number of bytes filled in the buffer
 430  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 431  * @remarks     Application would be responsible for managing/releasing data
 432  * @see         mm_attrs_set_data
 433  */
 434 int mm_attrs_get_data(MMHandleType attrs, int id, void **data, int *size);
 435
 436 /**
 437  * This function is to set range of attribute with given id.
 438  *
 439  * @param       attrs           [in]    List of attributes
 440  * @param       id              [in]    ID of attribute
 441  * @param       min             [in]    Minimum value of range
 442  * @param       max             [in]    Maximum value of range
 443  *
 444  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 445  * @see         mm_attrs_get_range
 446  */
 447 int mm_attrs_set_range(MMHandleType attrs, int id, int min, int max);
 448
 449 /**
 450  * This function is to get range of attribute with given id.
 451  *
 452  * @param       attrs           [in]    List of attributes
 453  * @param       id              [in]    ID of attribute
 454  * @param       min             [out]   Minimum value of range
 455  * @param       max             [out]   Maximum value of range
 456  *
 457  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 458  * @see         mm_attrs_set_range
 459  */
 460 int mm_attrs_get_range(MMHandleType attrs, int id, int *min, int *max);
 461
 462 /**
 463  * This function is to set array of attribute with given id.
 464  *
 465  * @param       attrs           [in]    List of attributes
 466  * @param       id              [in]    ID of attribute
 467  * @param       array           [in]    Array of integer values
 468  * @param       count           [in]    Count of array
 469  *
 470  * @return      This function returns the array of attribute on success, or NULL pointer on failure.
 471  * @see         mm_attrs_get_array
 472  */
 473 int mm_attrs_set_array(MMHandleType attrs, int id, int *array, int count);
 474
 475 /**
 476  * This function is to get array of attribute with given id.
 477  *
 478  * @param       attrs           [in]    List of attributes
 479  * @param       id              [in]    ID of attribute
 480  * @param       array           [out] Contains the array of attribute on success,
 481  *                                               or NULL pointer on failure.
 482  * @param       count           [out] Count of array
 483  *
 484  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 485  * @remarks     Application would be responsible for managing/releasing the array
 486  * @see         mm_attrs_set_array
 487  */
 488 int mm_attrs_get_array(MMHandleType attrs, int id, int **array, int *count );
 489
 490
 491 /**
 492  * A function to get  information of the attribute
 493  *
 494  * @param       attrs           [in]    List of attributes
 495  * @param       id              [in]    ID of attribute
 496  * @param       array           [out] Contains the array of attribute on success,
 497  *                                               or NULL pointer on failure.
 498  * @param       count           [out] Count of array
 499  *
 500  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 501  * @remarks     Application would be responsible for managing/releasing the array
 502  * @see         mm_attrs_set_info
 503  */
 504 int mm_attrs_get_info(MMHandleType h, int idx, MMAttrsInfo *info);
 505
 506
 507 /**
 508  * This function is to get array of attribute with given id.
 509  *
 510  * @param       attrs           [in]    List of attributes
 511  * @param       id              [in]    ID of attribute
 512  * @param       array           [out] Contains the array of attribute on success,
 513  *                                               or NULL pointer on failure.
 514  * @param       count           [out] Count of array
 515  *
 516  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 517  * @remarks     Application would be responsible for managing/releasing the array
 518  * @see         mm_attrs_set_array
 519  */
 520 int mm_attrs_get_info_by_name(MMHandleType h, const char *attr_name, MMAttrsInfo *info);
 521
 522 /**
 523  * Sets properties on an object.
 524
 525  * @param       attrs                                   [in]    List of attributes
 526  * @param       err_attr_name                   [out] the name of attributes that occurs error. Free this variable after use.
 527  * @param       attribute_name  [in]    name of the first property to set
 528  * @param       ...                                     [in]    value for the first property, followed optionally by more
 529  *  name/value pairs, followed by %NULL
 530  *
 531  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 532  * @remarks     Multiple setter of attribute
 533  * @see         mm_attrs_set_int, mm_attrs_set_string, ...
 534  */
 535 int mm_attrs_multiple_set(MMHandleType handle,  char **err_attr_name, const char *attribute_name, ...) __NULL_TERMINATED;
 536
 537
 538 /**
 539  * Gets properties on an object.
 540
 541  * @param       attrs                                   [in]    List of attributes
 542  * @param       err_attr_name                   [out] the name of attributes that occurs error. Free this variable after use.
 543  * @param       attribute_name  [in]    name of the first property to set
 544  * @param       ...                                     [in]    value for the first property, followed optionally by more
 545  *  name/value pairs, followed by %NULL
 546  *
 547  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 548  * @remarks     Multiple setter of attribute
 549  * @see         mm_attrs_set_int, mm_attrs_set_string, ...
 550  */
 551 int mm_attrs_multiple_get(MMHandleType handle,  char **err_attr_name, const char *attribute_name, ...) __NULL_TERMINATED;
 552
 553
 554 /**
 555  * Sets properties on an object with va_list param.
 556
 557  * @param       attrs                                   [in]    List of attributes
 558  * @param       err_attr_name                   [out] the name of attributes that occurs error. Free this variable after use.
 559  * @param       attribute_name  [in]    name of the first property to set
 560  * @param       var_args                                [in]    variable arguments
 561  *
 562  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 563  * @remarks     Multiple setter of attribute
 564  * @see         mm_attrs_multiple_set
 565  */
 566 int mm_attrs_set_valist (MMHandleType attrs, char **err_attr_name, const char *attribute_name, va_list var_args);
 567
 568
 569 /**
 570  * Gets properties on an object with va_list param.
 571
 572  * @param       attrs                                   [in]    List of attributes
 573  * @param       err_attr_name                   [out] the name of attributes that occurs error. Free this variable after use.
 574  * @param       attribute_name  [in]    name of the first property to set
 575  * @param       var_args                                [in]    variable arguments
 576  *
 577  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 578  * @remarks     Multiple setter of attribute
 579  * @see         mm_attrs_multiple_get
 580  */
 581 int mm_attrs_get_valist (MMHandleType attrs, char **err_attr_name, const char *attribute_name, va_list var_args);
 582
 583 /**
 584  * @}
 585  */
 586
 587 #ifdef __cplusplus
 588         }
 589 #endif
 590
 591 #endif /* __MM_ATTRS_H__ */