include/service-adapter/sa_elements.h

   1 /*
   2  * oma-ds-agent
   3  * Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4  *
   5  * Licensed under the Apache License, Version 2.0 (the License);
   6  * you may not use this file except in compliance with the License.
   7  * You may obtain a copy of the License at
   8  *
   9  *     http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  * Unless required by applicable law or agreed to in writing, software
  12  * distributed under the License is distributed on an "AS IS" BASIS,
  13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  * See the License for the specific language governing permissions and
  15  * limitations under the License.
  16  */
  17
  18 /**
  19  *   @SA_Elements.h
  20  *   @version                                                                   0.1
  21  *   @brief                                                                             This file is the header file of interface of elements structure
  22  */
  23
  24 #ifndef SA_ELEMENTS_H_
  25 #define SA_ELEMENTS_H_
  26
  27 #include "service-adapter/sa_define.h"
  28
  29 /**
  30  * @par Description: API to create anchor_s structure
  31  *
  32  * @par Purpose:
  33  * @par Typical use case:
  34  * @par Method of function operation:
  35  * @par Important notes:
  36  * @param[in]           string type, last anchor
  37  * @param[in]           string type, next anchor
  38  * @param[out]          anchor_s structure
  39  *
  40  * @return                              ERROR_INTERNAL_OK on success
  41  *                                                      ERROR_INTERNAL_NOT_DEFINED, ERROR_INTERNAL_NO_MEMORY on error
  42  * @par Errors:
  43  *
  44  * @pre None.
  45  * @post
  46  * @see
  47  * @remarks None.
  48  *
  49  * @par Sample Code:
  50  * @code
  51  * @endcode
  52  */
  53 sa_error_type_e create_anchor(char *last, char *next, anchor_s ** anchor);
  54
  55 /**
  56  * @par Description: API to set anchor in item_s structure
  57  *
  58  * @par Purpose:
  59  * @par Typical use case:
  60  * @par Method of function operation:
  61  * @par Important notes:
  62  * @param[in]           item_s structure
  63  * @param[in]           anchor_s structure
  64  *
  65  * @return                              ERROR_INTERNAL_OK on success
  66  *                                                      ERROR_INTERNAL_NOT_DEFINED, ERROR_INTERNAL_NO_MEMORY on error
  67  * @par Errors:
  68  *
  69  * @pre None.
  70  * @post
  71  * @see
  72  * @remarks None.
  73  *
  74  * @par Sample Code:
  75  * @code
  76  * @endcode
  77  */
  78 sa_error_type_e set_item_anchor(item_s * item, anchor_s * anchor);
  79
  80 /**
  81  * @par Description: API to set last anchor in anchor_s structure
  82  *
  83  * @par Purpose:
  84  * @par Typical use case:
  85  * @par Method of function operation:
  86  * @par Important notes:
  87  * @param[in]           anchor_s structure
  88  * @param[in]           string type, last anchor
  89  *
  90  * @return                              ERROR_INTERNAL_OK on success
  91  *                                                      ERROR_INTERNAL_NOT_DEFINED on error
  92  * @par Errors:
  93  *
  94  * @pre None.
  95  * @post
  96  * @see
  97  * @remarks None.
  98  *
  99  * @par Sample Code:
 100  * @code
 101  * @endcode
 102  */
 103 sa_error_type_e set_last_anchor(anchor_s * anchor, char *lastAnchor);
 104
 105 /**
 106  * @par Description: API to set next anchor in anchor_s structure
 107  *
 108  * @par Purpose:
 109  * @par Typical use case:
 110  * @par Method of function operation:
 111  * @par Important notes:
 112  * @param[in]           anchor_s structure
 113  * @param[in]           string type, next anchor
 114  *
 115  * @return                              ERROR_INTERNAL_OK on success
 116  *                                                      ERROR_INTERNAL_NOT_DEFINED on error
 117  * @par Errors:
 118  *
 119  * @pre None.
 120  * @post
 121  * @see
 122  * @remarks None.
 123  *
 124  * @par Sample Code:
 125  * @code
 126  * @endcode
 127  */
 128 sa_error_type_e set_next_anchor(anchor_s * anchor, char *nextAnchor);
 129
 130 /**
 131  * @par Description: API to free anchor_s structure
 132  *
 133  * @par Purpose:
 134  * @par Typical use case:
 135  * @par Method of function operation:
 136  * @par Important notes:
 137  * @param[in]           anchor_s structure
 138  *
 139  * @return                              ERROR_INTERNAL_OK on success
 140  *                                                      ERROR_INTERNAL_NOT_DEFINED on error
 141  * @par Errors:
 142  *
 143  * @pre None.
 144  * @post
 145  * @see
 146  * @remarks None.
 147  *
 148  * @par Sample Code:
 149  * @code
 150  * @endcode
 151  */
 152 void free_anchor(anchor_s * anchor);
 153
 154 /**
 155  * @par Description: API to create location_s structure
 156  *
 157  * @par Purpose:
 158  * @par Typical use case:
 159  * @par Method of function operation:
 160  * @par Important notes:
 161  * @param[in]           string type, location uri
 162  * @param[in]           string type, location name
 163  * @param[out]          location_s structure
 164  *
 165  * @return                              ERROR_INTERNAL_OK on success
 166  *                                                      ERROR_INTERNAL_NO_MEMORY, ERROR_INTERNAL_NOT_DEFINED on error
 167  * @par Errors:
 168  *
 169  * @pre None.
 170  * @post
 171  * @see
 172  * @remarks None.
 173  *
 174  * @par Sample Code:
 175  * @code
 176  * @endcode
 177  */
 178 sa_error_type_e create_location(char *loc_uri, char *loc_name, location_s ** location);
 179
 180 /**
 181  * @par Description: API to duplicate location_s structure
 182  *
 183  * @par Purpose:
 184  * @par Typical use case:
 185  * @par Method of function operation:
 186  * @par Important notes:
 187  * @param[in]           location_s structure
 188  *
 189  * @return                              location_s structure                            on success
 190  *                                                      NULL                                                            on error
 191  * @par Errors:
 192  *
 193  * @pre None.
 194  * @post
 195  * @see
 196  * @remarks None.
 197  *
 198  * @par Sample Code:
 199  * @code
 200  * @endcode
 201  */
 202 location_s *dup_location(location_s * location);
 203
 204 /**
 205  * @par Description: API to get location name from location_s structure
 206  *
 207  * @par Purpose:
 208  * @par Typical use case:
 209  * @par Method of function operation:
 210  * @par Important notes:
 211  * @param[in]           location_s structure
 212  *
 213  * @return                              location name                                   on success
 214  *                                                      NULL                                                            on error
 215  * @par Errors:
 216  *
 217  * @pre None.
 218  * @post
 219  * @see
 220  * @remarks None.
 221  *
 222  * @par Sample Code:
 223  * @code
 224  * @endcode
 225  */
 226 char *get_location_loc_name(location_s * location);
 227
 228 /**
 229  * @par Description: API to get location uri from location_s structure
 230  *
 231  * @par Purpose:
 232  * @par Typical use case:
 233  * @par Method of function operation:
 234  * @par Important notes:
 235  * @param[in]           location_s structure
 236  *
 237  * @return                              location uri                                                    on success
 238  *                                                      NULL                                                            on error
 239  * @par Errors:
 240  *
 241  * @pre None.
 242  * @post
 243  * @see
 244  * @remarks None.
 245  *
 246  * @par Sample Code:
 247  * @code
 248  * @endcode
 249  */
 250 char *get_location_loc_uri(location_s * location);
 251
 252 /**
 253  * @par Description: API to free location_s structure
 254  *
 255  * @par Purpose:
 256  * @par Typical use case:
 257  * @par Method of function operation:
 258  * @par Important notes:
 259  * @param[in]           location_s structure
 260  *
 261  * @return
 262  *
 263  * @par Errors:
 264  *
 265  * @pre None.
 266  * @post
 267  * @see
 268  * @remarks None.
 269  *
 270  * @par Sample Code:
 271  * @code
 272  * @endcode
 273  */
 274 void free_location(location_s * location);
 275
 276 /**
 277  * @par Description: API to create cred_s structure
 278  *
 279  * @par Purpose:
 280  * @par Typical use case:
 281  * @par Method of function operation:
 282  * @par Important notes:
 283  * @param[in]           string type, ID
 284  * @param[in]           string type, password
 285  * @param[in]           enum type, authentication type(basic, md5..)
 286  * @param[in]           enum type, format type(base64..)
 287  * @param[in]           string type, credential
 288  * @param[out]          cred_s structure
 289  *
 290  * @return                              ERROR_INTERNAL_OK on success
 291  *                                                      ERROR_INTERNAL_NO_MEMORY, ERROR_INTERNAL_NOT_DEFINED on error
 292  * @par Errors:
 293  *
 294  * @pre None.
 295  * @post
 296  * @see
 297  * @remarks None.
 298  *
 299  * @par Sample Code:
 300  * @code
 301  * @endcode
 302  */
 303 sa_error_type_e create_cred(char *user_name, char *pwd, auth_type_e auth_type, format_type_e format_type, char *data, cred_s ** cred);
 304
 305 /**
 306  * @par Description: API to create cred_s structure
 307  *
 308  * @par Purpose:
 309  * @par Typical use case:
 310  * @par Method of function operation:
 311  * @par Important notes:
 312  * @param[in]           enum type, authentication type(basic, md5..)
 313  * @param[in]           credential
 314  *
 315  * @return                              cred_s structure on success
 316  *                                                      NULL on error
 317  * @par Errors:
 318  *
 319  * @pre None.
 320  * @post
 321  * @see
 322  * @remarks None.
 323  *
 324  * @par Sample Code:
 325  * @code
 326  * @endcode
 327  */
 328 cred_s *create_cred_with_data(auth_type_e auth_type, char *data);
 329
 330 /**
 331  * @par Description: API to duplicate cred_s structure
 332  *
 333  * @par Purpose:
 334  * @par Typical use case:
 335  * @par Method of function operation:
 336  * @par Important notes:
 337  * @param[in]           cred_s structure
 338  *
 339  * @return                              cred_s structure on success
 340  *                                                      NULL on error
 341  * @par Errors:
 342  *
 343  * @pre None.
 344  * @post
 345  * @see
 346  * @remarks None.
 347  *
 348  * @par Sample Code:
 349  * @code
 350  * @endcode
 351  */
 352 cred_s *dup_cred(cred_s * cred);
 353
 354 /**
 355  * @par Description: API to set format type in cred_s structure
 356  *
 357  * @par Purpose:
 358  * @par Typical use case:
 359  * @par Method of function operation:
 360  * @par Important notes:
 361  * @param[in]           cred_s structure
 362  * @param[in]           format type(base64..)
 363  *
 364  * @return
 365  *
 366  * @par Errors:
 367  *
 368  * @pre None.
 369  * @post
 370  * @see
 371  * @remarks None.
 372  *
 373  * @par Sample Code:
 374  * @code
 375  * @endcode
 376  */
 377 void set_cred_format_type(cred_s * cred, format_type_e format_type);
 378
 379 /**
 380  * @par Description: API to free cred_s structure
 381  *
 382  * @par Purpose:
 383  * @par Typical use case:
 384  * @par Method of function operation:
 385  * @par Important notes:
 386  * @param[in]           cred_s structure
 387  *
 388  * @return
 389  *
 390  * @par Errors:
 391  *
 392  * @pre None.
 393  * @post
 394  * @see
 395  * @remarks None.
 396  *
 397  * @par Sample Code:
 398  * @code
 399  * @endcode
 400  */
 401 void free_cred(cred_s * cred);
 402
 403 /**
 404  * @par Description: API to create syncml_s structure
 405  *
 406  * @par Purpose:
 407  * @par Typical use case:
 408  * @par Method of function operation:
 409  * @par Important notes:
 410  * @param[in]           sync_hdr_s structure
 411  * @param[in]           GList type, list of status_s structure
 412  * @param[in]           GList type, list of command_s structure
 413  * @param[in]           int type, final flag
 414  * @param[out]          syncml_s structure
 415  *
 416  * @return                              ERROR_INTERNAL_OK on success
 417  *                                                      ERROR_INTERNAL_NO_MEMORY, ERROR_INTERNAL_NOT_DEFINED on error
 418  *
 419  * @par Errors:
 420  *
 421  * @pre None.
 422  * @post
 423  * @see
 424  * @remarks None.
 425  *
 426  * @par Sample Code:
 427  * @code
 428  * @endcode
 429  */
 430 sa_error_type_e create_syncml(sync_hdr_s * sync_hdr, GList * status, GList * commands, int is_final, syncml_s ** syncml);
 431
 432 /**
 433  * @par Description: API to free syncml_s structure
 434  *
 435  * @par Purpose:
 436  * @par Typical use case:
 437  * @par Method of function operation:
 438  * @par Important notes:
 439  * @param[in]           syncml_s structure
 440  *
 441  * @return
 442  *
 443  * @par Errors:
 444  *
 445  * @pre None.
 446  * @post
 447  * @see
 448  * @remarks None.
 449  *
 450  * @par Sample Code:
 451  * @code
 452  * @endcode
 453  */
 454 void free_syncml(syncml_s * syncml);
 455
 456 /**
 457  * @par Description: API to create sync_hdr_s structure
 458  *
 459  * @par Purpose:
 460  * @par Typical use case:
 461  * @par Method of function operation:
 462  * @par Important notes:
 463  * @param[in]           session_s structure
 464  * @param[out]          sync_hdr_s structure
 465  *
 466  * @return                              ERROR_INTERNAL_OK on success
 467  *                                                      ERROR_INTERNAL_NO_MEMORY, ERROR_INTERNAL_NOT_DEFINED on error
 468  *
 469  * @par Errors:
 470  *
 471  * @pre None.
 472  * @post
 473  * @see
 474  * @remarks None.
 475  *
 476  * @par Sample Code:
 477  * @code
 478  * @endcode
 479  */
 480 sa_error_type_e create_sync_hdr(session_s * session, sync_hdr_s ** sync_hdr);
 481
 482 /**
 483  * @par Description: API to free SyncHdr structure
 484  *
 485  * @par Purpose:
 486  * @par Typical use case:
 487  * @par Method of function operation:
 488  * @par Important notes:
 489  * @param[in]           SyncHdr structure
 490  *
 491  * @return
 492  *
 493  * @par Errors:
 494  *
 495  * @pre None.
 496  * @post
 497  * @see
 498  * @remarks None.
 499  *
 500  * @par Sample Code:
 501  * @code
 502  * @endcode
 503  */
 504 void free_sync_hdr(sync_hdr_s * sync_hdr);
 505
 506 /**
 507  * @par Description: API to create item_s structure
 508  *
 509  * @par Purpose:
 510  * @par Typical use case:
 511  * @par Method of function operation:
 512  * @par Important notes:
 513  * @param[in]
 514  * @param[out]
 515  *
 516  * @return                      item_s structure on success
 517  *                                              NULL on error
 518  *
 519  * @par Errors:
 520  *
 521  * @pre None.
 522  * @post
 523  * @see
 524  * @remarks None.
 525  *
 526  * @par Sample Code:
 527  * @code
 528  * @endcode
 529  */
 530 item_s *create_item();
 531
 532 /**
 533  * @par Description: API to create item_s structure using data
 534  *
 535  * @par Purpose:
 536  * @par Typical use case:
 537  * @par Method of function operation:
 538  * @par Important notes:
 539  * @param[in]           data
 540  * @param[in]           size of data
 541  * @param[out]
 542  *
 543  * @return                      item_s structure on success
 544  *                                              NULL on error
 545  *
 546  * @par Errors:
 547  *
 548  * @pre None.
 549  * @post
 550  * @see
 551  * @remarks None.
 552  *
 553  * @par Sample Code:
 554  * @code
 555  * @endcode
 556  */
 557 item_s *create_item_for_data(const char *data, unsigned int size);
 558
 559 /**
 560  * @par Description: API to create item_s structure using DevInf
 561  *
 562  * @par Purpose:
 563  * @par Typical use case:
 564  * @par Method of function operation:
 565  * @par Important notes:
 566  * @param[in]           devinf_s structure
 567  * @param[out]
 568  *
 569  * @return                      item_s structure on success
 570  *                                              NULL on error
 571  *
 572  * @par Errors:
 573  *
 574  * @pre None.
 575  * @post
 576  * @see
 577  * @remarks None.
 578  *
 579  * @par Sample Code:
 580  * @code
 581  * @endcode
 582  */
 583 item_s *create_item_for_devinf(devinf_s * devinf);
 584
 585 /**
 586  * @par Description: API to set location_s(target) structure in item_s structure
 587  *
 588  * @par Purpose:
 589  * @par Typical use case:
 590  * @par Method of function operation:
 591  * @par Important notes:
 592  * @param[in]           item_s structure
 593  * @param[in]           location_s structure
 594  * @param[out]
 595  *
 596  * @return
 597  *
 598  * @par Errors:
 599  *
 600  * @pre None.
 601  * @post
 602  * @see
 603  * @remarks None.
 604  *
 605  * @par Sample Code:
 606  * @code
 607  * @endcode
 608  */
 609 void set_item_target(item_s * item, location_s * target);
 610
 611 /**
 612  * @par Description: API to set location_s(source) structure in item_s structure
 613  *
 614  * @par Purpose:
 615  * @par Typical use case:
 616  * @par Method of function operation:
 617  * @par Important notes:
 618  * @param[in]           item_s structure
 619  * @param[in]           location_s structure
 620  * @param[out]
 621  *
 622  * @return
 623  *
 624  * @par Errors:
 625  *
 626  * @pre None.
 627  * @post
 628  * @see
 629  * @remarks None.
 630  *
 631  * @par Sample Code:
 632  * @code
 633  * @endcode
 634  */
 635 void set_item_source(item_s * item, location_s * source);
 636
 637 /**
 638  * @par Description: API to free item_s structure
 639  *
 640  * @par Purpose:
 641  * @par Typical use case:
 642  * @par Method of function operation:
 643  * @par Important notes:
 644  * @param[in]           item_s structure
 645  * @param[out]
 646  *
 647  * @return
 648  *
 649  * @par Errors:
 650  *
 651  * @pre None.
 652  * @post
 653  * @see
 654  * @remarks None.
 655  *
 656  * @par Sample Code:
 657  * @code
 658  * @endcode
 659  */
 660 void free_item(item_s * item);
 661
 662 /**
 663  * @par Description: API to duplicate chal_s structure
 664  *
 665  * @par Purpose:
 666  * @par Typical use case:
 667  * @par Method of function operation:
 668  * @par Important notes:
 669  * @param[in]           chal_s structure
 670  * @param[out]
 671  *
 672  * @return                      chal_s structure on success
 673  *                                              NULL on error
 674  *
 675  * @par Errors:
 676  *
 677  * @pre None.
 678  * @post
 679  * @see
 680  * @remarks None.
 681  *
 682  * @par Sample Code:
 683  * @code
 684  * @endcode
 685  */
 686 chal_s *dup_chal(chal_s * chal);
 687
 688 /**
 689  * @par Description: API to free chal_s structure
 690  *
 691  * @par Purpose:
 692  * @par Typical use case:
 693  * @par Method of function operation:
 694  * @par Important notes:
 695  * @param[in]           chal_s structure
 696  * @param[out]
 697  *
 698  * @return
 699  *
 700  * @par Errors:
 701  *
 702  * @pre None.
 703  * @post
 704  * @see
 705  * @remarks None.
 706  *
 707  * @par Sample Code:
 708  * @code
 709  * @endcode
 710  */
 711 void free_chal(chal_s * chal);
 712
 713 /**
 714  * @par Description: API to compare server credential with local credential
 715  *
 716  * @par Purpose:
 717  * @par Typical use case:
 718  * @par Method of function operation:
 719  * @par Important notes:
 720  * @param[in]           cred_s structure
 721  * @param[in]           cred_s structure
 722  * @param[out]
 723  *
 724  * @return                      ERROR_INTERNAL_OK on success
 725  *                                              ERROR_AUTH_REJECTED, ERROR_INTERNAL_NOT_DEFINED on error
 726  *
 727  * @par Errors:
 728  *
 729  * @pre None.
 730  * @post
 731  * @see
 732  * @remarks None.
 733  *
 734  * @par Sample Code:
 735  * @code
 736  * @endcode
 737  */
 738 sa_error_type_e compare_cred(cred_s * hdr_cred, cred_s * session_cred);
 739
 740 /**
 741  * @par Description: API to convert auth_type_e
 742  *
 743  * @par Purpose:
 744  * @par Typical use case:
 745  * @par Method of function operation:
 746  * @par Important notes:
 747  * @param[in]           string type, auth type
 748  * @param[out]
 749  *
 750  * @return                      AUTH_TYPE_MD5, AUTH_TYPE_BASIC on success
 751  *                                              AUTH_TYPE_UNKNOWN on error
 752  *
 753  * @par Errors:
 754  *
 755  * @pre None.
 756  * @post
 757  * @see
 758  * @remarks None.
 759  *
 760  * @par Sample Code:
 761  * @code
 762  * @endcode
 763  */
 764 auth_type_e convert_auth_type(char *auth_type);
 765
 766 /**
 767  * @par Description: API to convert format_type_e
 768  *
 769  * @par Purpose:
 770  * @par Typical use case:
 771  * @par Method of function operation:
 772  * @par Important notes:
 773  * @param[in]           string type, format type
 774  * @param[out]
 775  *
 776  * @return                      FORMAT_TYPE_BASE64 on success
 777  *                                              FORMAT_TYPE_UNKNOWN on error
 778  *
 779  * @par Errors:
 780  *
 781  * @pre None.
 782  * @post
 783  * @see
 784  * @remarks None.
 785  *
 786  * @par Sample Code:
 787  * @code
 788  * @endcode
 789  */
 790 format_type_e convert_format_type(char *format_type);
 791
 792 /**
 793  * @par Description: API to create mem_s structure
 794  *
 795  * @par Purpose:
 796  * @par Typical use case:
 797  * @par Method of function operation:
 798  * @par Important notes:
 799  * @param[in]
 800  * @param[out]
 801  *
 802  * @return                      mem_s structure on success
 803  *                                              NULL on error
 804  *
 805  * @par Errors:
 806  *
 807  * @pre None.
 808  * @post
 809  * @see
 810  * @remarks None.
 811  *
 812  * @par Sample Code:
 813  * @code
 814  * @endcode
 815  */
 816 mem_s *create_mem();
 817
 818 /**
 819  * @par Description: API to set shared_mem
 820  *
 821  * @par Purpose:
 822  * @par Typical use case:
 823  * @par Method of function operation:
 824  * @par Important notes:
 825  * @param[in] mem
 826  * @param[in] shared_mem
 827  *
 828  * @return
 829  *
 830  * @par Errors:
 831  *
 832  * @pre None.
 833  * @post
 834  * @see
 835  * @remarks None.
 836  *
 837  * @par Sample Code:
 838  * @code
 839  * @endcode
 840  */
 841 void set_mem_shared_mem(mem_s * mem, int shared_mem);
 842
 843 /**
 844  * @par Description: API to set free_mem
 845  *
 846  * @par Purpose:
 847  * @par Typical use case:
 848  * @par Method of function operation:
 849  * @par Important notes:
 850  * @param[in] mem
 851  * @param[in] free_mem
 852  *
 853  * @return
 854  *
 855  * @par Errors:
 856  *
 857  * @pre None.
 858  * @post
 859  * @see
 860  * @remarks None.
 861  *
 862  * @par Sample Code:
 863  * @code
 864  * @endcode
 865  */
 866 void set_mem_free_mem(mem_s * mem, unsigned int free_mem);
 867
 868 /**
 869  * @par Description: API to set free_id
 870  *
 871  * @par Purpose:
 872  * @par Typical use case:
 873  * @par Method of function operation:
 874  * @par Important notes:
 875  * @param[in] mem
 876  * @param[in] free_id
 877  *
 878  * @return
 879  *
 880  * @par Errors:
 881  *
 882  * @pre None.
 883  * @post
 884  * @see
 885  * @remarks None.
 886  *
 887  * @par Sample Code:
 888  * @code
 889  * @endcode
 890  */
 891 void set_mem_free_id(mem_s * mem, unsigned int free_id);
 892
 893 #endif                          /* SA_ELEMENTS_H_ */