plugins/messages.h

   1 /*
   2  *
   3  *  OBEX Server
   4  *
   5  *  Copyright (C) 2010-2011  Nokia Corporation
   6  *
   7  *
   8  *  This program is free software; you can redistribute it and/or modify
   9  *  it under the terms of the GNU General Public License as published by
  10  *  the Free Software Foundation; either version 2 of the License, or
  11  *  (at your option) any later version.
  12  *
  13  *  This program is distributed in the hope that it will be useful,
  14  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16  *  GNU General Public License for more details.
  17  *
  18  *  You should have received a copy of the GNU General Public License
  19  *  along with this program; if not, write to the Free Software
  20  *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  21  *
  22  */
  23
  24 #include <glib.h>
  25 #include <stdint.h>
  26
  27 /* Those are used by backend to notify transport plugin which properties did it
  28  * send.
  29  */
  30 #define PMASK_SUBJECT                   0x0001
  31 #define PMASK_DATETIME                  0x0002
  32 #define PMASK_SENDER_NAME               0x0004
  33 #define PMASK_SENDER_ADDRESSING         0x0008
  34 #define PMASK_RECIPIENT_NAME            0x0010
  35 #define PMASK_RECIPIENT_ADDRESSING      0x0020
  36 #define PMASK_TYPE                      0x0040
  37 #define PMASK_SIZE                      0x0080
  38 #define PMASK_RECEPTION_STATUS          0x0100
  39 #define PMASK_TEXT                      0x0200
  40 #define PMASK_ATTACHMENT_SIZE           0x0400
  41 #define PMASK_PRIORITY                  0x0800
  42 #define PMASK_READ                      0x1000
  43 #define PMASK_SENT                      0x2000
  44 #define PMASK_PROTECTED                 0x4000
  45 #define PMASK_REPLYTO_ADDRESSING        0x8000
  46
  47 /* This one is used in a response to GetMessagesListing. Use PMASK_* values to
  48  * notify the plugin which members are actually set. Backend shall not omit
  49  * properties required by MAP specification (subject, datetime,
  50  * recipient_addressing, type, size, reception_status, attachment_size) unless
  51  * ordered by PARAMETERMASK. Boolean values should be probably
  52  * always sent (need checking). Handle is mandatory. Plugin will filter out any
  53  * properties that were not wanted by MCE.
  54  *
  55  * Handle shall be set to hexadecimal representation with upper-case letters. No
  56  * prefix shall be appended and without no zeros. This corresponds to PTS
  57  * behaviour described in comments to the MAP specification.
  58  *
  59  * The rest of char * fields shall be set according to the MAP specification
  60  * rules.
  61  */
  62 struct messages_message {
  63         uint32_t mask;
  64         char *handle;
  65         char *subject;
  66         char *datetime;
  67         char *sender_name;
  68         char *sender_addressing;
  69         char *replyto_addressing;
  70         char *recipient_name;
  71         char *recipient_addressing;
  72         char *type;
  73         char *reception_status;
  74         char *size;
  75         char *attachment_size;
  76         gboolean text;
  77         gboolean read;
  78         gboolean sent;
  79         gboolean protect;
  80         gboolean priority;
  81 };
  82
  83 /* Type of message event to be delivered to MNS server */
  84 enum messages_event_type {
  85         MET_NEW_MESSAGE,
  86         MET_DELIVERY_SUCCESS,
  87         MET_SENDING_SUCCESS,
  88         MET_DELIVERY_FAILURE,
  89         MET_SENDING_FAILURE,
  90         MET_MEMORY_FULL,
  91         MET_MEMORY_AVAILABLE,
  92         MET_MESSAGE_DELETED,
  93         MET_MESSAGE_SHIFT
  94 };
  95
  96 /* Data for sending MNS notification. Handle shall be formatted as described in
  97  * messages_message.
  98  */
  99 struct messages_event {
 100         enum messages_event_type type;
 101         uint8_t instance_id;
 102         char *handle;
 103         char *folder;
 104         char *old_folder;
 105         char *msg_type;
 106 };
 107
 108 /* parameter_mask: |-ed PMASK_* values
 109  * See MAP specification for the rest.
 110  */
 111 struct messages_filter {
 112         uint32_t parameter_mask;
 113         uint8_t type;
 114         const char *period_begin;
 115         const char *period_end;
 116         uint8_t read_status;
 117         const char *recipient;
 118         const char *originator;
 119         uint8_t priority;
 120 };
 121
 122 /* This is called once after server starts.
 123  *
 124  * Returns value less than zero if error. This will prevent MAP plugin from
 125  * starting.
 126  */
 127 int messages_init(void);
 128
 129 /* This gets called right before server finishes
 130  */
 131 void messages_exit(void);
 132
 133 /* Starts a new MAP session.
 134  *
 135  * session: variable to store pointer to backend session data. This one shall be
 136  * passed to all in-session calls.
 137  *
 138  * If session start succeeded, backend shall return 0. Otherwise the error value
 139  * will be sent as a response to OBEX connect.
 140  */
 141 int messages_connect(void **session);
 142
 143 /* Closes a MAP session.
 144  *
 145  * This call should free buffer reserved by messages_connect.
 146  */
 147 void messages_disconnect(void *session);
 148
 149 /******************************************************************************
 150  * NOTE on callbacks.
 151  *
 152  * All functions requiring callbacks have to call them asynchronously.
 153  * 'user_data' is for passing arbitrary user data.
 154  *
 155  * Functions for GetMessagesListing, GetFolder listing and GetMessage call their
 156  * callbacks multiple times - one for each listing entry or message body chunk.
 157  * To indicate the end of operation backend must call callback with the data
 158  * pointer parameter set to NULL.
 159  *
 160  * If err == -EAGAIN the transport * plugin does not wake IO.
 161  *
 162  * Keep in mind that application parameters has to be send first. Therefore the
 163  * first time err == 0 and thus sending is started, callback will use provided
 164  * parameters (e.g. size in case of folder listing) to build applications
 165  * parameters header used in response. In any other case those parameters will
 166  * be ignored.
 167  *
 168  * If err != 0 && err != -EAGAIN, the operation is finished immediately and err
 169  * value is used to set the error code in OBEX response.
 170  ******************************************************************************/
 171
 172 /* Registers for messaging events notifications.
 173  *
 174  * session: Backend session.
 175  * send_event: Function that will be called to indicate a new event.
 176  *
 177  * To unregister currently registered notifications, call this with send_event
 178  * set to NULL.
 179  */
 180 int messages_set_notification_registration(void *session,
 181                 void (*send_event)(void *session,
 182                         const struct messages_event *event, void *user_data),
 183                 void *user_data);
 184
 185 /* Changes current directory.
 186  *
 187  * session: Backend session.
 188  * name: Subdirectory to go to. If empty or null and cdup is false, go to the
 189  *      root directory.
 190  * cdup: If true, go up one level first.
 191  */
 192 int messages_set_folder(void *session, const char *name, gboolean cdup);
 193
 194 /* Retrieves subdirectories listing from a current directory.
 195  *
 196  * session: Backend session.
 197  * name: Optional subdirectory name (not strictly required by MAP).
 198  * max: Maximum number of entries to retrieve.
 199  * offset: Offset of the first entry.
 200  * size: Total size of listing to be returned.
 201  *
 202  * Callback shall be called for every entry of the listing. 'name' is the
 203  * subdirectory name.
 204  */
 205 typedef void (*messages_folder_listing_cb)(void *session, int err,
 206                 uint16_t size, const char *name, void *user_data);
 207
 208 int messages_get_folder_listing(void *session, const char *name, uint16_t max,
 209                                 uint16_t offset,
 210                                 messages_folder_listing_cb callback,
 211                                 void *user_data);
 212
 213 /* Retrieves messages listing from a current directory.
 214  *
 215  * session: Backend session.
 216  * name: Optional subdirectory name.
 217  * max: Maximum number of entries to retrieve.
 218 #ifdef TIZEN_PATCH
 219  * offset: Offset of the first entry.
 220  * subject_len: Maximum string length of the "subject" parameter in the entries.
 221 #endif
 222  * filter: Filter to apply on returned message listing.
 223  * size: Total size of listing to be returned.
 224  * newmsg: Indicates presence of unread messages.
 225  *
 226  * Callback shall be called for every entry of the listing, giving message data
 227  * in 'message'.
 228  */
 229 typedef void (*messages_get_messages_listing_cb)(void *session, int err,
 230                                         uint16_t size, gboolean newmsg,
 231                                         const struct messages_message *message,
 232                                         void *user_data);
 233 #ifdef TIZEN_PATCH
 234 int messages_get_messages_listing(void *session, const char *name,
 235                                 uint16_t max, uint16_t offset, uint8_t subject_len,
 236                                 const struct messages_filter *filter,
 237                                 messages_get_messages_listing_cb callback,
 238                                 void *user_data);
 239 #else
 240 int messages_get_messages_listing(void *session, const char *name,
 241                                 uint16_t max, uint16_t offset,
 242                                 const struct messages_filter *filter,
 243                                 messages_get_messages_listing_cb callback,
 244                                 void *user_data);
 245 #endif
 246
 247 #define MESSAGES_ATTACHMENT     (1 << 0)
 248 #define MESSAGES_UTF8           (1 << 1)
 249 #define MESSAGES_FRACTION       (1 << 2)
 250 #define MESSAGES_NEXT           (1 << 3)
 251
 252 /* Retrieves bMessage object (see MAP specification, ch. 3.1.3) of a given
 253  * message.
 254  *
 255  * session: Backend session.
 256  * handle: Handle of the message to retrieve.
 257  * flags: or-ed mask of following:
 258  *      MESSAGES_ATTACHMENT: Selects whether or not attachments (if any) are to
 259  *              be included.
 260  *      MESSAGES_UTF8: If true, convert message to utf-8. Otherwise use native
 261  *              encoding.
 262  *      MESSAGES_FRACTION: If true, deliver fractioned message.
 263  *      MESSAGES_NEXT: If fraction is true this indicates whether to retrieve
 264  *              first fraction
 265  *      or the next one.
 266  * fmore: Indicates whether next fraction is available.
 267  * chunk: chunk of bMessage body
 268  *
 269  * Callback allows for returning bMessage in chunks.
 270  */
 271 typedef void (*messages_get_message_cb)(void *session, int err, gboolean fmore,
 272         const char *chunk, void *user_data);
 273
 274 int messages_get_message(void *session, const char *handle,
 275                                         unsigned long flags,
 276                                         messages_get_message_cb callback,
 277                                         void *user_data);
 278
 279 /* Informs Message Server to Update Inbox via network.
 280  *
 281  * session: Backend session.
 282  * user_data: User data if any to be sent.
 283  * Callback shall be called for every update inbox request received from MCE.
 284  */
 285 typedef void (*messages_update_inbox_cb)(void *session, int err,
 286                                                         void *user_data);
 287
 288 int messages_update_inbox(void *session, messages_update_inbox_cb callback,
 289                                                         void *user_data);
 290 #ifdef TIZEN_PATCH
 291
 292 /* Informs Message Server to modify status of the message.
 293  *
 294  * session: Backend session.
 295  * handle: Unique identifier to the message.
 296  * indicator: To indicate which status information is to be modified,
 297  *      "readStatus" or "deleteStatus".
 298  * value: To indicate the value of the indicator
 299  *      read/unread for "readstatus" and deleted/undeleted for "deleteStatus".
 300  * Callback shall be called for every message status update request
 301  *      recieved from MCE.
 302  * user_data: User data if any to be sent.
 303  */
 304 typedef void (*messages_set_message_status_cb)(void *session, int err,
 305                 void *user_data);
 306
 307 int messages_set_message_status(void *session, const char *handle,
 308                                         int indicator, int value,
 309                                         messages_set_message_status_cb callback,
 310                                         void *user_data);
 311 #endif
 312
 313
 314 #ifdef TIZEN_PATCH
 315
 316 /* Informs Message Server to modify status of the message.
 317  *
 318  * session: Backend session.
 319  * address: Remote device address that request notification registraton.
 320  * status: To indicate message notification service
 321  * Callback shall be called for every notification registration request.
 322  * user_data: User data if any to be sent.
 323  */
 324 typedef void (*messages_notification_registration_cb)(void *session, int err,
 325                 void *user_data);
 326
 327 int messages_notification_registration(void *session,
 328                                         char *address, int status,
 329                                         messages_notification_registration_cb callback,
 330                                         void *user_data);
 331 #endif
 332
 333 /* Aborts currently pending request.
 334  *
 335  * session: Backend session.
 336  */
 337 void messages_abort(void *session);