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         char *period_begin;
 115         char *period_end;
 116         uint8_t read_status;
 117         char *recipient;
 118         char *originator;
 119         uint8_t priority;
 120 };
 121
 122 #ifdef TIZEN_PATCH
 123 /* To store Application parameters.
 124  * See MAP specification for the details.
 125  * filter - Parameters on which we filter the message list to be sent.
 126  * maxlistcount - Maximum number of Messages or folders to be sent,
 127  *              if not mentioned it is 1024.
 128  * offset - Offset from where the list is to be sent, if not mentioned it is 0.
 129  * attachment - Indicates if any attachment i.e. ON or OFF.
 130  * transparent -To tell MSE that no copy shall me kept in Sent folder.
 131  * retry -To indicate if successive attempts to be made, incase network is not
 132  *              accessible.
 133  * newmessage -To indicate unread messages in message listing.
 134  * notification_status -Indicates Incoming message notification On/Off.
 135  * mas_instance -Indicate corresponding 'MASInstanceID', as only one MNS
 136  *                       connection can be made with an MSE.
 137  * folderlisting_size -Used in response if the value of maxlistcount is 0.
 138  * messagelisting_size -Used in response if the value of maxlistcount is 0.
 139  * subject_length -Maximum length of the Subject in Messages-Listing.
 140  * fraction_request -Used only if the message is fractioned.
 141  * fraction_delivery -Used only if fraction_request is present in Get Message
 142  *                               Request.
 143  * charset - Determines trans-coding of the text i.e. "Native" or "UTF-8".
 144  * status_indicator - Indicates which status information is to be modified
 145  *              i.e. "readStatus" or "deletedStatus".
 146  * status_value - Indicates value to status_indicator i.e. "yes" or "no".
 147  * msetime -To report the local time of MSE and its UTC Offset.
 148  */
 149 struct apparam_field {
 150         struct messages_filter *filter;
 151         uint16_t maxlistcount;
 152         uint16_t offset;
 153         uint8_t attachment;
 154         uint8_t transparent;
 155         uint8_t retry;
 156         uint8_t newmessage;
 157         uint8_t notification_status;
 158         uint8_t mas_instance;
 159         uint16_t folderlisting_size;
 160         uint16_t messagelisting_size;
 161         uint8_t subject_length;
 162         uint8_t charset;
 163         uint8_t fraction_request;
 164         uint8_t fraction_delivery;
 165         uint8_t status_indicator;
 166         uint8_t status_value;
 167         char *msetime;
 168 };
 169 #endif
 170
 171 /* This is called once after server starts.
 172  *
 173  * Returns value less than zero if error. This will prevent MAP plugin from
 174  * starting.
 175  */
 176 int messages_init(void);
 177
 178 /* This gets called right before server finishes
 179  */
 180 void messages_exit(void);
 181
 182 /* Starts a new MAP session.
 183  *
 184  * session: variable to store pointer to backend session data. This one shall be
 185  * passed to all in-session calls.
 186  *
 187  * If session start succeeded, backend shall return 0. Otherwise the error value
 188  * will be sent as a response to OBEX connect.
 189  */
 190 int messages_connect(void **session);
 191
 192 /* Closes a MAP session.
 193  *
 194  * This call should free buffer reserved by messages_connect.
 195  */
 196 void messages_disconnect(void *session);
 197
 198 /******************************************************************************
 199  * NOTE on callbacks.
 200  *
 201  * All functions requiring callbacks have to call them asynchronously.
 202  * 'user_data' is for passing arbitrary user data.
 203  *
 204  * Functions for GetMessagesListing, GetFolder listing and GetMessage call their
 205  * callbacks multiple times - one for each listing entry or message body chunk.
 206  * To indicate the end of operation backend must call callback with the data
 207  * pointer parameter set to NULL.
 208  *
 209  * If err == -EAGAIN the transport * plugin does not wake IO.
 210  *
 211  * Keep in mind that application parameters has to be send first. Therefore the
 212  * first time err == 0 and thus sending is started, callback will use provided
 213  * parameters (e.g. size in case of folder listing) to build applications
 214  * parameters header used in response. In any other case those parameters will
 215  * be ignored.
 216  *
 217  * If err != 0 && err != -EAGAIN, the operation is finished immediately and err
 218  * value is used to set the error code in OBEX response.
 219  ******************************************************************************/
 220
 221 /* Registers for messaging events notifications.
 222  *
 223  * session: Backend session.
 224  * send_event: Function that will be called to indicate a new event.
 225  *
 226  * To unregister currently registered notifications, call this with send_event
 227  * set to NULL.
 228  */
 229 int messages_set_notification_registration(void *session,
 230                 void (*send_event)(void *session,
 231                         const struct messages_event *event, void *user_data),
 232                 void *user_data);
 233
 234 /* Changes current directory.
 235  *
 236  * session: Backend session.
 237  * name: Subdirectory to go to. If empty or null and cdup is false, go to the
 238  *      root directory.
 239  * cdup: If true, go up one level first.
 240  */
 241 int messages_set_folder(void *session, const char *name, gboolean cdup);
 242
 243 /* Retrieves subdirectories listing from a current directory.
 244  *
 245  * session: Backend session.
 246  * name: Optional subdirectory name (not strictly required by MAP).
 247  * max: Maximum number of entries to retrieve.
 248  * offset: Offset of the first entry.
 249  * size: Total size of listing to be returned.
 250  *
 251  * Callback shall be called for every entry of the listing. 'name' is the
 252  * subdirectory name.
 253  */
 254 typedef void (*messages_folder_listing_cb)(void *session, int err,
 255                 uint16_t size, const char *name, void *user_data);
 256
 257 int messages_get_folder_listing(void *session, const char *name, uint16_t max,
 258                                 uint16_t offset,
 259                                 messages_folder_listing_cb callback,
 260                                 void *user_data);
 261
 262 /* Retrieves messages listing from a current directory.
 263  *
 264  * session: Backend session.
 265  * name: Optional subdirectory name.
 266  * max: Maximum number of entries to retrieve.
 267  * filter: Filter to apply on returned message listing.
 268  * size: Total size of listing to be returned.
 269  * newmsg: Indicates presence of unread messages.
 270  *
 271  * Callback shall be called for every entry of the listing, giving message data
 272  * in 'message'.
 273  */
 274 typedef void (*messages_get_messages_listing_cb)(void *session, int err,
 275                                         uint16_t size, gboolean newmsg,
 276                                         const struct messages_message *message,
 277                                         void *user_data);
 278
 279 int messages_get_messages_listing(void *session, const char *name,
 280                                 uint16_t max, uint16_t offset,
 281                                 const struct messages_filter *filter,
 282                                 messages_get_messages_listing_cb callback,
 283                                 void *user_data);
 284
 285 #define MESSAGES_ATTACHMENT     (1 << 0)
 286 #define MESSAGES_UTF8           (1 << 1)
 287 #define MESSAGES_FRACTION       (1 << 2)
 288 #define MESSAGES_NEXT           (1 << 3)
 289
 290 /* Retrieves bMessage object (see MAP specification, ch. 3.1.3) of a given
 291  * message.
 292  *
 293  * session: Backend session.
 294  * handle: Handle of the message to retrieve.
 295  * flags: or-ed mask of following:
 296  *      MESSAGES_ATTACHMENT: Selects whether or not attachments (if any) are to
 297  *              be included.
 298  *      MESSAGES_UTF8: If true, convert message to utf-8. Otherwise use native
 299  *              encoding.
 300  *      MESSAGES_FRACTION: If true, deliver fractioned message.
 301  *      MESSAGES_NEXT: If fraction is true this indicates whether to retrieve
 302  *              first fraction
 303  *      or the next one.
 304  * fmore: Indicates whether next fraction is available.
 305  * chunk: chunk of bMessage body
 306  *
 307  * Callback allows for returning bMessage in chunks.
 308  */
 309 typedef void (*messages_get_message_cb)(void *session, int err, gboolean fmore,
 310         const char *chunk, void *user_data);
 311
 312 int messages_get_message(void *session, const char *handle,
 313                                         unsigned long flags,
 314                                         messages_get_message_cb callback,
 315                                         void *user_data);
 316
 317 /* Informs Message Server to Update Inbox via network.
 318  *
 319  * session: Backend session.
 320  * user_data: User data if any to be sent.
 321  * Callback shall be called for every update inbox request recieved from MCE.
 322  */
 323 typedef void (*messages_update_inbox_cb)(void *session, int err,
 324                                                         void *user_data);
 325
 326 int messages_update_inbox(void *session, messages_update_inbox_cb callback,
 327                                                         void *user_data);
 328 #ifdef TIZEN_PATCH
 329
 330 /* Informs Message Server to modify status of the message.
 331  *
 332  * session: Backend session.
 333  * handle: Unique identifier to the message.
 334  * indicator: To indicate which status information is to be modified,
 335  *      "readStatus" or "deleteStatus".
 336  * value: To indicate the value of the indicator
 337  *      read/unread for "readstatus" and deleted/undeleted for "deleteStatus".
 338  * Callback shall be called for every message status update request
 339  *      recieved from MCE.
 340  * user_data: User data if any to be sent.
 341  */
 342 typedef void (*messages_set_message_status_cb)(void *session, int err,
 343                 void *user_data);
 344
 345 int messages_set_message_status(void *session, const char *handle,
 346                                         int indicator, int value,
 347                                         messages_set_message_status_cb callback,
 348                                         void *user_data);
 349 #endif
 350
 351 /* Aborts currently pending request.
 352  *
 353  * session: Backend session.
 354  */
 355 void messages_abort(void *session);