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  * @param       attrs           [in] MMAttrs handle
 150  * @param       attr_name       [in] attribute name
 151  * @param       val             [in] integer value to set
 152  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 153  */
 154 int mm_attrs_set_int_by_name(MMHandleType attrs, const char *attr_name, int val);
 155
 156
 157 /**
 158  * This function is to get the number of attribute in the MMAttrs.
 159  * @param       attrs           [in]    Handle of attributes list
 160  * @param       size            [out]   Number of attributes
 161  * @return      This function returns the number of attributes in the attribute list.
 162  */
 163 int mm_attrs_get_size(MMHandleType attrs, int *size);
 164
 165
 166 /**
 167  * This function is to get the name of attribute at the given index.
 168  * @param       attrs           [in]    Handle of attributes list
 169  * @param       index           [in]    Index of the attribute
 170  * @param       name            [out]   Name of attribute
 171  * @return      This function returns the name of attribute on success, or NULL
 172  *                      on failure.
 173  */
 174 int mm_attrs_get_name(MMHandleType attrs, int index, char **name);
 175
 176
 177 /**
 178  * This function is to get the index of attribute at the given name.
 179  * @param       attrs           [in]    Handle of attributes list
 180  * @param       attr_name       [in]    Name of attribute
 181  * @param       index           [out]   Index of attribute
 182  * @return      This function returns the index of the attribute on success,
 183  *                      or negative value on failure.
 184  */
 185 int mm_attrs_get_index(MMHandleType attrs, const char *attr_name, int *index);
 186
 187
 188 /**
 189  * This function is to get the integer value from the attribute by name.
 190  * @param       attrs           [in]    Handle of attributes list
 191  * @param       attr_name       [in]    Name of attribute
 192  * @param       val                     [out]   Value of attribute
 193  * @return      This function returns attribute value
 194  */
 195 int mm_attrs_get_int_by_name(MMHandleType attrs, const char *attr_name, int *val);
 196
 197
 198 /**
 199  * This function is to set the string to attribute by name.
 200  * @param       attrs           [in] MMAttrs handle
 201  * @param       attr_name       [in] attribute name
 202  * @param       string          [in] string value to set
 203  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 204  */
 205 int mm_attrs_set_string_by_name(MMHandleType attrs, const char *attr_name, const char *string);
 206
 207
 208 /**
 209  * This function is to get the string from the attribute by name.
 210  * @param       attrs           [in]    Handle of attributes list
 211  * @param       attr_name       [in]    Name of attribute
 212  * @param       val                     [out]   Value of attribute
 213  * @return      This function returns the string value of attribute on success,
 214  *                      or NULL on failure
 215  */
 216 int mm_attrs_get_string_by_name(MMHandleType attrs, const char *attr_name, char **val);
 217
 218
 219 /**
 220  * This function is to set the data to the attribute by name.
 221  * @param       attrs           [in] MMAttrs handle
 222  * @param       attr_name       [in] attribute name
 223  * @param       data            [in] data pointer to set
 224  * @param       size            [in] data size to set
 225  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 226  */
 227 int mm_attrs_set_data_by_name(MMHandleType attrs, const char *attr_name, void *data, int size);
 228
 229 /**
 230  * This function is to get the data from the attribute by name.
 231  * @param       attrs                   [in]    Handle of attributes list
 232  * @param       attr_name       [in]    Name of attribute
 233  * @param       data                    [out] data pointer to set
 234  * @return      This function returns user defined value on success, or NULL
 235  *                      on failure
 236  */
 237 int mm_attrs_get_data_by_name(MMHandleType attrs, const char *attr_name, void **data);
 238
 239
 240 /**
 241  * This function is to retrieve type of attribute.
 242  * @param       attrs           [in] List of attributes
 243  * @param       id              [in] ID of attribute
 244  * @param       attrtype        [out] On return contains type of attribute
 245  * @return      This function returns MM_ERROR_NONE.
 246  * @see         MMAttrsType
 247  */
 248 int mm_attrs_get_type(MMHandleType attrs, int id, MMAttrsType *attrtype);
 249
 250
 251 /**
 252  * This function is to get flags of attribute with given id.
 253  * @param       attrs           [in] List of attributes
 254  * @param       id              [in] ID of attribute
 255  * @param       flags           [out] On return contains flags of attribute.
 256  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 257  * @see         MMAttrsFlag
 258  */
 259 int mm_attrs_get_flags(MMHandleType attrs, int id, int *flags);
 260
 261
 262 /**
 263  * This function is to get valid value type of attribute with given id.
 264  * @param       attrs           [in] List of attributes
 265  * @param       id              [in] ID of attribute
 266  * @param       type            [out] On return contains valid value type of attribute
 267  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 268  * @see         MMAttrsType
 269  */
 270 int mm_attrs_get_valid_type(MMHandleType attrs, int id, int *type);
 271
 272
 273 /**
 274  * This function is to get valid range of attribute with given id.
 275  * @param       attrs           [in] List of attributes
 276  * @param       id              [in] ID of attribute
 277  * @param       min             [out] minimum value of the valid range.
 278  * @param       max             [out] maximum value of the valid range.
 279  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 280  */
 281 int mm_attrs_get_valid_range(MMHandleType attrs, int id, int *min, int *max);
 282
 283
 284 /**
 285  * This function is to get valid array of attribute with given id.
 286  * @param       attrs           [in] list of attributes
 287  * @param       id              [in] ID of attribute
 288  * @param       count           [out] number of array
 289  * @param       array           [out] on return contains valid array of attribute
 290  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 291  */
 292 int mm_attrs_get_valid_array(MMHandleType attrs, int id, int *count,  int **array);
 293
 294
 295 /**
 296  * This function is to get valid double type range of attribute with given id.
 297  * @param       attrs           [in] List of attributes
 298  * @param       id              [in] ID of attribute
 299  * @param       min             [out] minimum value of the valid range.
 300  * @param       max             [out] maximum value of the valid range.
 301  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 302  */
 303 int mm_attrs_get_valid_double_range(MMHandleType h, int idx, double *min, double *max);
 304
 305
 306 /**
 307  * This function is to get valid double type array of attribute with given id.
 308  * @param       attrs           [in] list of attributes
 309  * @param       id              [in] ID of attribute
 310  * @param       count           [out] number of array
 311  * @param       array           [out] on return contains valid array of attribute
 312  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 313  */
 314 int mm_attrs_get_valid_double_array(MMHandleType h, int idx, int *count,  double **array);
 315
 316
 317 /**
 318  * This function is to set integer value to attribute with given id.
 319  * @param       attrs           [in] List of attributes
 320  * @param       id              [in] ID of attribute
 321  * @param       val             [in] integer value to set
 322  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 323  * @see         mm_attrs_get_int
 324  */
 325 int mm_attrs_set_int(MMHandleType attrs, int id, int val);
 326
 327
 328 /**
 329  * This function is to get integer value to attribute with given id.
 330  * @param       attrs           [in] List of attributes
 331  * @param       id              [in] ID of attribute
 332  * @param       val             [out] On return contains integer value of attribute
 333  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 334  * @remarks     If type of attributes is not an integer type, the value which is returned by this function is meaningless.
 335  * @see         mm_attrs_get_int
 336  */
 337 int mm_attrs_get_int(MMHandleType attrs, int id,  int *val);
 338
 339
 340 /**
 341  * This function is to set double value to attribute with given id.
 342  *
 343  * @param       attrs           [in]    List of attributes
 344  * @param       id              [in]    ID of attribute
 345  * @param       val             [in]    Integer value to set
 346  *
 347  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 348  * @see         mm_attrs_get_double
 349  */
 350 int mm_attrs_set_double(MMHandleType attrs, int id, double val);
 351
 352
 353 /**
 354  * This function is to set the double value to the attribute by name.
 355  *
 356  * @param       attrs           [in]    Handle of attributes list
 357  * @param       attr_name       [in]    Name of attribute
 358  * @param       val             [in]    Integer value to set
 359  *
 360  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 361  */
 362 int mm_attrs_set_double_by_name(MMHandleType attrs, const char *attr_name, double val);
 363
 364
 365 /**
 366  * This function is to get double value to attribute with given id.
 367  *
 368  * @param       attrs           [in]    List of attributes
 369  * @param       id              [in]    ID of attribute
 370  * @param       attrval         [out]   On return contains double value of attribute on success, or invalid value.
 371  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 372  * @see         mm_attrs_set_double
 373  */
 374 int mm_attrs_get_double(MMHandleType attrs, int id, double *attrval);
 375
 376
 377 /**
 378  * This function is to get the double value from the attribute by name.
 379  *
 380  * @param       attrs           [in]    Handle of attributes list
 381  * @param       attr_name       [in]    Name of attribute
 382  * @param       val             [out]   Double value to set
 383  *
 384  * @return      This function returns attribute value
 385  */
 386 int mm_attrs_get_double_by_name(MMHandleType attrs, const char *attr_name, double *val);
 387
 388
 389 /**
 390  * This function is to set string to attribute with given id.
 391  * @param       attrs           [in] List of attributes
 392  * @param       id              [in] ID of attribute
 393  * @param       string          [in] String to set
 394  * @param       size            [in] length of string to set
 395  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 396  * @see         mm_attrs_get_string
 397  */
 398 int mm_attrs_set_string(MMHandleType attrs, int id, const char *string, int size);
 399
 400
 401 /**
 402  * This function is to get string to attribute with given id.
 403  * @param       attrs           [in] List of attributes
 404  * @param       id              [in] ID of attribute
 405  * @param       sval            [in] Placeholder to output string buffer
 406  * @param       size            [in] The field contains number of characters filled in the buffer
 407  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 408  * @remarks     Application would be responsible for managing/releasing the string
 409  * @see         mm_attrs_set_string
 410  */
 411 int mm_attrs_get_string(MMHandleType attrs, int id,char **sval, int *size);
 412
 413
 414 /**
 415  * This function is to set pointer to attribute with given id.
 416  * @param       attrs           [in] List of attributes
 417  * @param       id              [in] ID of attribute
 418  * @param       data            [in] data to set
 419  * @param       size            [in] Length of input data
 420  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 421  * @remarks     Data type is the reference to memory which is allocated by user. The allocated memory must be freed by user.
 422  * @see         mm_attrs_get_data
 423  */
 424 int mm_attrs_set_data(MMHandleType attrs, int id, void *data,  int size);
 425
 426 /**
 427  * This function is to get pointer to attribute with given id.
 428  * @param       attrs           [in] List of attributes
 429  * @param       id              [in] ID of attribute
 430  * @param       data            [out] Placeholder to output data buffer
 431  * @param       size            [out] The field contains number of bytes filled in the buffer
 432  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 433  * @remarks     Application would be responsible for managing/releasing data
 434  * @see         mm_attrs_set_data
 435  */
 436 int mm_attrs_get_data(MMHandleType attrs, int id, void **data, int *size);
 437
 438
 439 /**
 440  * A function to get  information of the attribute
 441  *
 442  * @param       attrs           [in]    List of attributes
 443  * @param       id              [in]    ID of attribute
 444  * @param       array           [out] Contains the array of attribute on success,
 445  *                                               or NULL pointer on failure.
 446  * @param       count           [out] Count of array
 447  *
 448  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 449  * @remarks     Application would be responsible for managing/releasing the array
 450  * @see         mm_attrs_set_info
 451  */
 452 int mm_attrs_get_info(MMHandleType h, int idx, MMAttrsInfo *info);
 453
 454
 455 /**
 456  * This function is to get array of attribute with given id.
 457  *
 458  * @param       attrs           [in]    List of attributes
 459  * @param       id              [in]    ID of attribute
 460  * @param       array           [out] Contains the array of attribute on success,
 461  *                                               or NULL pointer on failure.
 462  * @param       count           [out] Count of array
 463  *
 464  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 465  * @remarks     Application would be responsible for managing/releasing the array
 466  * @see         mm_attrs_set_array
 467  */
 468 int mm_attrs_get_info_by_name(MMHandleType h, const char *attr_name, MMAttrsInfo *info);
 469
 470 /**
 471  * Sets properties on an object.
 472
 473  * @param       attrs                                   [in]    List of attributes
 474  * @param       err_attr_name                   [out] the name of attributes that occurs error. Free this variable after use.
 475  * @param       attribute_name  [in]    name of the first property to set
 476  * @param       ...                                     [in]    value for the first property, followed optionally by more
 477  *  name/value pairs, followed by %NULL
 478  *
 479  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 480  * @remarks     Multiple setter of attribute
 481  * @see         mm_attrs_set_int, mm_attrs_set_string, ...
 482  */
 483 int mm_attrs_multiple_set(MMHandleType handle,  char **err_attr_name, const char *attribute_name, ...) __NULL_TERMINATED;
 484
 485
 486 /**
 487  * Gets properties on an object.
 488
 489  * @param       attrs                                   [in]    List of attributes
 490  * @param       err_attr_name                   [out] the name of attributes that occurs error. Free this variable after use.
 491  * @param       attribute_name  [in]    name of the first property to set
 492  * @param       ...                                     [in]    value for the first property, followed optionally by more
 493  *  name/value pairs, followed by %NULL
 494  *
 495  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 496  * @remarks     Multiple setter of attribute
 497  * @see         mm_attrs_set_int, mm_attrs_set_string, ...
 498  */
 499 int mm_attrs_multiple_get(MMHandleType handle,  char **err_attr_name, const char *attribute_name, ...) __NULL_TERMINATED;
 500
 501
 502 /**
 503  * Sets properties on an object with va_list param.
 504
 505  * @param       attrs                                   [in]    List of attributes
 506  * @param       err_attr_name                   [out] the name of attributes that occurs error. Free this variable after use.
 507  * @param       attribute_name  [in]    name of the first property to set
 508  * @param       var_args                                [in]    variable arguments
 509  *
 510  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 511  * @remarks     Multiple setter of attribute
 512  * @see         mm_attrs_multiple_set
 513  */
 514 int mm_attrs_set_valist (MMHandleType attrs, char **err_attr_name, const char *attribute_name, va_list var_args);
 515
 516
 517 /**
 518  * Gets properties on an object with va_list param.
 519
 520  * @param       attrs                                   [in]    List of attributes
 521  * @param       err_attr_name                   [out] the name of attributes that occurs error. Free this variable after use.
 522  * @param       attribute_name  [in]    name of the first property to set
 523  * @param       var_args                                [in]    variable arguments
 524  *
 525  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 526  * @remarks     Multiple setter of attribute
 527  * @see         mm_attrs_multiple_get
 528  */
 529 int mm_attrs_get_valist (MMHandleType attrs, char **err_attr_name, const char *attribute_name, va_list var_args);
 530
 531 /**
 532  * @}
 533  */
 534
 535 #ifdef __cplusplus
 536         }
 537 #endif
 538
 539 #endif /* __MM_ATTRS_H__ */