include/mapi/MapiControl.h

   1 /*
   2 *
   3 * Copyright (c) 2000-2012 Samsung Electronics Co., Ltd. All Rights Reserved.
   4 *
   5 * This file is part of msg-service.
   6 *
   7 * Contact: Jaeyun Jeong <jyjeong@samsung.com>
   8 *          Sangkoo Kim <sangkoo.kim@samsung.com>
   9 *          Seunghwan Lee <sh.cat.lee@samsung.com>
  10 *          SoonMin Jung <sm0415.jung@samsung.com>
  11 *          Jae-Young Lee <jy4710.lee@samsung.com>
  12 *          KeeBum Kim <keebum.kim@samsung.com>
  13 *
  14 * PROPRIETARY/CONFIDENTIAL
  15 *
  16 * This software is the confidential and proprietary information of
  17 * SAMSUNG ELECTRONICS ("Confidential Information"). You shall not
  18 * disclose such Confidential Information and shall use it only in
  19 * accordance with the terms of the license agreement you entered
  20 * into with SAMSUNG ELECTRONICS.
  21 *
  22 * SAMSUNG make no representations or warranties about the suitability
  23 * of the software, either express or implied, including but not limited
  24 * to the implied warranties of merchantability, fitness for a particular
  25 * purpose, or non-infringement. SAMSUNG shall not be liable for any
  26 * damages suffered by licensee as a result of using, modifying or
  27 * distributing this software or its derivatives.
  28 *
  29 */
  30
  31 /**
  32  *      @file           MapiControl.h
  33  *      @brief          Defines control API of messaging framework
  34  *      @version        1.0
  35  */
  36
  37 #ifndef MAPI_CONTROL_H
  38 #define MAPI_CONTROL_H
  39
  40 /**
  41  *      @section                Introduction
  42  *      - Introduction : Overview on Messaging Control API
  43  *      @section                Program
  44  *      - Program : Messaging Control API Reference
  45  */
  46
  47 /*==================================================================================================
  48                                          INCLUDE FILES
  49 ==================================================================================================*/
  50
  51 #include "MsgTypes.h"
  52
  53 #ifdef __cplusplus
  54 extern "C"
  55 {
  56 #endif
  57
  58 /**
  59  *      @ingroup                MESSAGING_FRAMEWORK
  60  *      @defgroup       MESSAGING_CONTROL_API   Messaging Control API
  61  *      @{
  62  */
  63
  64 /*==================================================================================================
  65                                      FUNCTION PROTOTYPES
  66 ==================================================================================================*/
  67
  68 /**
  69
  70  * \par Description:
  71  * Opens a channel between an application and messaging framework.
  72  *
  73  * \par Purpose:
  74  * For application to utilize the services of Messaging Framework, this API should be called to establish connection between the application and Messaging Framework.
  75  *
  76  * \par Typical use case:
  77  * Any application which utilizes the services of Messaging Framework needs to call this API.
  78  *
  79  * \par Method of function operation:
  80  * Check for Message Server ready status. If ready connect to the Messaging Server socket and pass the handle application.
  81  *
  82  * \par Sync (or) Async:
  83  * This is a Synchronous API.
  84  *
  85  * \par Important notes:
  86  * - The handle parameter returned must be used by application for further API calls to Messaging Service \n
  87  * - memory for the handle need not be allocated by the application \n
  88  * - An error will be returned in case Messaging Service is not running.
  89  *
  90  * \param MSG_HANDLE_T    input - handle to be passed for all Messaging Services .
  91  *
  92  * \return Return Type (int) \n
  93  * - MSG_SUCCESS        - Successfully connected to Messaging Service \n
  94  * - MSG_ERR_NULL_POINTER       -       Input parameter is NULL.
  95  * - MSG_ERR_MEMORY_ERROR -     Memory error.
  96  * - MSG_ERR_COMMUNICATION_ERROR        - Communication error between client and server \n
  97  *
  98  * \par Prospective clients:
  99  * External/Native Apps using Messaging Services.
 100  *
 101  * \par Related functions:
 102  * None
 103  *
 104  * \par Known issues/bugs:
 105  * None
 106  *
 107  * \par Sample code:
 108  * \code
 109  * ...
 110  *
 111  * MSG_HANDLE_T msgHandle = NULL;
 112  * MSG_ERROR_T err = MSG_SUCCESS;
 113  *
 114  * err = msg_open_msg_handle(&msgHandle);
 115  *
 116  * if (err != MSG_SUCCESS)
 117  * {
 118  *      sprintf(str, "msg_open_msg_handle() Fail [%d]", err);
 119  *      print(str);
 120  *
 121  *      return err; // if success, return OPERATION_SUCCESS. Or if fail, return related error code.
 122  * }
 123  *
 124  * ...
 125  * \endcode
 126  */
 127 /*================================================================================================*/
 128 int msg_open_msg_handle(MSG_HANDLE_T *handle);
 129
 130
 131 /**
 132
 133  * \par Description:
 134  * Closes the channel between application and messaging framework.
 135  *
 136  * \par Purpose:
 137  * Once application utilizes services of Messaging Service, this API needs to be invoked the close the channel between application and Messaging Service.
 138  *
 139  * \par Typical use case:
 140  * Any application which has completed using services of Messaging Framework needs to call this API.
 141  *
 142  * \par Method of function operation:
 143  * Closes the connection to Messaging Service and deleted the reference to the handle object
 144  *
 145  * \par Sync (or) Async:
 146  * This is a Synchronous API.
 147  *
 148  * \par Important notes:
 149  * - The handle parameter returned must be used by application for further API calls to Messaging Service \n
 150  * - memory for the handle need not be allocated by the application \n
 151  * - An error will be returned in case Messaging Service is not running.
 152  *
 153  * \param MSG_HANDLE_T    input - handle to be passed for all Messaging Services .
 154  *
 155  * \return Return Type (int) \n
 156  * - MSG_SUCCESS        - Successfully connected to Messaging Service \n
 157  * - MSG_ERR_NULL_POINTER       -       Input parameter is NULL.
 158  * - MSG_ERR_COMMUNICATION_ERROR        - Communication error between client and server \n
 159  *
 160  * \par Prospective clients:
 161  * External/Native Apps using Messaging Services.
 162  *
 163  * \par Related functions:
 164  * None
 165  *
 166  * \par Known issues/bugs:
 167  * None
 168  *
 169  * \par Sample code:
 170  * \code
 171  * ...
 172  *
 173  * MSG_HANDLE_T msgHandle = NULL;
 174  * MSG_ERROR_T err = MSG_SUCCESS;
 175  *
 176  * ...
 177  *
 178  * err = msg_open_msg_handle(&msgHandle);
 179  *
 180  * ...
 181  *
 182  * err = msg_close_msg_handle(&msgHandle);
 183  *
 184  * if (err != MSG_SUCCESS)
 185  * {
 186  *      sprintf(str, "msg_close_msg_handle() Fail [%d]", err);
 187  *      print(str);
 188  *
 189  *      return err; // if success, return OPERATION_SUCCESS. Or if fail, return related error code.
 190  * }
 191  *
 192  * ...
 193  * \endcode
 194  */
 195 /*================================================================================================*/
 196 int msg_close_msg_handle(MSG_HANDLE_T *handle);
 197
 198 /**
 199  *      @}
 200  */
 201
 202 #ifdef __cplusplus
 203 }
 204 #endif
 205
 206 #endif // MAPI_STORAGE_H
 207