include/ServiceAdapter/SA_Elements.h

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