plugins/phonebook.h

   1 /*
   2  *
   3  *  OBEX Server
   4  *
   5  *  Copyright (C) 2007-2010  Marcel Holtmann <marcel@holtmann.org>
   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 #define EOL     "\r\n"
  25 #define VCARD_LISTING_BEGIN \
  26         "<?xml version=\"1.0\"?>" EOL\
  27         "<!DOCTYPE vcard-listing SYSTEM \"vcard-listing.dtd\">" EOL\
  28         "<vCard-listing version=\"1.0\">" EOL
  29 #define VCARD_LISTING_ELEMENT "<card handle = \"%d.vcf\" name = \"%s\"/>" EOL
  30 #define VCARD_LISTING_END "</vCard-listing>"
  31
  32 struct apparam_field {
  33         /* list and pull attributes */
  34         uint16_t maxlistcount;
  35         uint16_t liststartoffset;
  36
  37         /* pull and vcard attributes */
  38         uint64_t filter;
  39         uint8_t format;
  40
  41         /* list attributes only */
  42         uint8_t order;
  43         uint8_t searchattrib;
  44         uint8_t *searchval;
  45 };
  46
  47 /*
  48  * Interface between the PBAP core and backends to retrieve
  49  * all contacts that match the application parameters rules.
  50  * Contacts will be returned in the vcard format.
  51  */
  52 typedef void (*phonebook_cb) (const char *buffer, size_t bufsize,
  53                 int vcards, int missed, gboolean lastpart, void *user_data);
  54
  55 /*
  56  * Interface between the PBAP core and backends to
  57  * append a new entry in the PBAP folder cache.
  58  */
  59 #define PHONEBOOK_INVALID_HANDLE 0xffffffff
  60 typedef void (*phonebook_entry_cb) (const char *id, uint32_t handle,
  61                                         const char *name, const char *sound,
  62                                         const char *tel, void *user_data);
  63
  64 /*
  65  * After notify all entries to PBAP core, the backend
  66  * needs to notify that the operation has finished.
  67  */
  68 typedef void (*phonebook_cache_ready_cb) (void *user_data);
  69
  70 #ifdef TIZEN_PATCH
  71 typedef void (*phonebook_cache_clear_cb) (void *user_data);
  72 #endif
  73
  74
  75 int phonebook_init(void);
  76 void phonebook_exit(void);
  77
  78 #ifdef TIZEN_PATCH
  79 int phonebook_connect(void **user_data);
  80 void phonebook_disconnect(void *user_data);
  81 #endif
  82
  83
  84 /*
  85  * Changes the current folder in the phonebook back-end. The PBAP core
  86  * doesn't validate or restrict the possible values for the folders,
  87  * allowing non-standard backends implementation which doesn't follow
  88  * the PBAP virtual folder architecture. Validate the folder's name
  89  * is responsibility of the back-ends.
  90 */
  91 char *phonebook_set_folder(const char *current_folder,
  92                 const char *new_folder, uint8_t flags, int *err);
  93
  94 /*
  95  * phonebook_pull should be used only to prepare pull request - prepared
  96  * request data is returned by this function. Start of fetching data from
  97  * back-end will be done only after calling phonebook_pull_read with this
  98  * returned request given as a parameter.
  99  *
 100  * phonebook_req_finalize MUST always be used to free associated resources.
 101  */
 102 void *phonebook_pull(const char *name, const struct apparam_field *params,
 103                                 phonebook_cb cb, void *user_data, int *err);
 104
 105 /*
 106  * phonebook_pull_read should be used to start getting results from back-end.
 107  * The back-end can return data as one response or can return it many parts.
 108  * After obtaining one part, PBAP core need to call phonebook_pull_read with
 109  * the same request again to get more results from back-end.
 110  * The back-end MUST return only the content based on the application
 111  * parameters requested by the client.
 112  *
 113  * Returns error code or 0 in case of success
 114  */
 115 int phonebook_pull_read(void *request);
 116
 117 /*
 118  * Function used to retrieve a contact from the backend. Only contacts
 119  * found in the cache are requested to the back-ends. The back-end MUST
 120  * return only the content based on the application parameters requested
 121  * by the client.
 122  *
 123  * Return value is a pointer to asynchronous request to phonebook back-end.
 124  * phonebook_req_finalize MUST always be used to free associated resources.
 125  */
 126 void *phonebook_get_entry(const char *folder, const char *id,
 127                                 const struct apparam_field *params,
 128                                 phonebook_cb cb, void *user_data, int *err);
 129
 130 /*
 131  * PBAP core will keep the contacts cache per folder. SetPhoneBook or
 132  * PullvCardListing can invalidate the cache if the current folder changes.
 133  * Cache will store only the necessary information required to reply to
 134  * PullvCardListing request and verify if a given contact belongs to the
 135  * source.
 136  *
 137  * Return value is a pointer to asynchronous request to phonebook back-end.
 138  * phonebook_req_finalize MUST always be used to free associated resources.
 139  */
 140 void *phonebook_create_cache(const char *name, phonebook_entry_cb entry_cb,
 141                 phonebook_cache_ready_cb ready_cb, void *user_data, int *err);
 142
 143 /*
 144  * Finalizes request to phonebook back-end and deallocates associated
 145  * resources. Operation is canceled if not completed. This function MUST
 146  * always be used after any of phonebook_pull, phonebook_get_entry, and
 147  * phonebook_create_cache invoked.
 148  *
 149  * request is a pointer to asynchronous operation returned by phonebook_pull,
 150  * phonebook_get_entry, and phonebook_create_cache.
 151  */
 152 void phonebook_req_finalize(void *request);
 153
 154 #ifdef TIZEN_PATCH
 155 void phonebook_set_cache_notification(void *session,
 156                                 phonebook_cache_clear_cb cache_cb,
 157                                 void *user_data);
 158 #endif