1 2 /* 3 Meanwhile - Unofficial Lotus Sametime Community Client Library 4 Copyright (C) 2004 Christopher (siege) O'Brien 5 6 This library is free software; you can redistribute it and/or 7 modify it under the terms of the GNU Library General Public 8 License as published by the Free Software Foundation; either 9 version 2 of the License, or (at your option) any later version. 10 11 This library is distributed in the hope that it will be useful, 12 but WITHOUT ANY WARRANTY; without even the implied warranty of 13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 Library General Public License for more details. 15 16 You should have received a copy of the GNU Library General Public 17 License along with this library; if not, write to the Free 18 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 19 */ 20 21 #ifndef _MW_SRVC_STORE_H 22 #define _MW_SRVC_STORE_H 23 24 25 #include <glib.h> 26 #include "mw_common.h" 27 28 29 #ifdef __cplusplus 30 extern "C" { 31 #endif 32 33 34 /** Type identifier for the storage service */ 35 #define mwService_STORAGE 0x00000018 36 37 38 /** @struct mwServiceStorage 39 @see mwServiceStorage_new 40 41 Instance of the storage service */ 42 struct mwServiceStorage; 43 44 45 /** @struct mwStorage 46 47 Unit Represents information intended for loading from or saving to 48 the storage service */ 49 struct mwStorageUnit; 50 51 52 /** The upper limit of reserved Lotus keys */ 53 #define LOTUS_RESERVED_LIMIT 0x186a0 54 55 56 /** Check if a key is in the range of Lotus reserved keys */ 57 #define KEY_IS_LOTUS_RESERVED(key) \ 58 (((guint32) key) <= (LOTUS_RESERVED_LIMIT)) 59 60 61 /** Some common keys storage keys. Anything in the range 0x00 to 62 0x186a0 (100000) is reserved for use by the Lotus 63 clients. */ 64 enum mwStorageKey { 65 66 /** The buddy list, in the Sametime .dat file format. String */ 67 mwStore_AWARE_LIST = 0x00000000, 68 69 /** Default text for chat invitations. String */ 70 mwStore_INVITE_CHAT = 0x00000006, 71 72 /** Default text for meeting invitations. String */ 73 mwStore_INVITE_MEETING = 0x0000000e, 74 75 /** Last five Away messages, separated by semicolon. String */ 76 mwStore_AWAY_MESSAGES = 0x00000050, 77 78 /** Last five Busy (DND) messages, separated by semicolon. String */ 79 mwStore_BUSY_MESSAGES = 0x0000005a, 80 81 /** Last five Active messages, separated by semicolon. String */ 82 mwStore_ACTIVE_MESSAGES = 0x00000064, 83 }; 84 85 86 /** Appropriate function type for load and store callbacks. 87 @param srvc the storage service 88 @param result the result value of the load or store call 89 @param item the storage unit loaded or saved 90 @param data optional user data 91 */ 92 typedef void (*mwStorageCallback) 93 (struct mwServiceStorage *srvc, 94 guint32 result, struct mwStorageUnit *item, 95 gpointer data); 96 97 98 /** Allocates and initializes a storage service instance for use on 99 the passed session. */ 100 struct mwServiceStorage *mwServiceStorage_new(struct mwSession *); 101 102 103 /** create an empty storage unit */ 104 struct mwStorageUnit *mwStorageUnit_new(guint32 key); 105 106 107 /** creates a storage unit with the passed key, and a copy of data. */ 108 struct mwStorageUnit *mwStorageUnit_newOpaque(guint32 key, 109 struct mwOpaque *data); 110 111 112 /** creates a storage unit with the passed key, and an encapsulated 113 boolean value */ 114 struct mwStorageUnit *mwStorageUnit_newBoolean(guint32 key, 115 gboolean val); 116 117 118 struct mwStorageUnit *mwStorageUnit_newInteger(guint32 key, 119 guint32 val); 120 121 122 /** creates a storage unit with the passed key, and an encapsulated 123 string value. */ 124 struct mwStorageUnit *mwStorageUnit_newString(guint32 key, 125 const char *str); 126 127 128 /** get the key for the given storage unit */ 129 guint32 mwStorageUnit_getKey(struct mwStorageUnit *); 130 131 132 /** attempts to obtain a boolean value from a storage unit. If the 133 unit is empty, or does not contain the type in a recongnizable 134 format, val is returned instead */ 135 gboolean mwStorageUnit_asBoolean(struct mwStorageUnit *, gboolean val); 136 137 138 /** attempts to obtain a guint32 value from a storage unit. If the 139 unit is empty, or does not contain the type in a recognizable 140 format, val is returned instead */ 141 guint32 mwStorageUnit_asInteger(struct mwStorageUnit *, guint32 val); 142 143 144 /** attempts to obtain a string value from a storage unit. If the unit 145 is empty, or does not contain the type in a recognizable format, 146 NULL is returned instead. Note that the string returned is a copy, 147 and will need to be deallocated at some point. */ 148 char *mwStorageUnit_asString(struct mwStorageUnit *); 149 150 151 /** direct access to the opaque data backing the storage unit */ 152 struct mwOpaque *mwStorageUnit_asOpaque(struct mwStorageUnit *); 153 154 155 /** clears and frees a storage unit */ 156 void mwStorageUnit_free(struct mwStorageUnit *); 157 158 159 /** Initiates a load call to the storage service. If the service is 160 not currently available, the call will be cached and processed 161 when the service is started. 162 163 @param srvc the storage service 164 @param item storage unit to load 165 @param cb callback function when the load call completes 166 @param data user data for callback 167 @param data_free optional cleanup function for user data 168 */ 169 void mwServiceStorage_load(struct mwServiceStorage *srvc, 170 struct mwStorageUnit *item, 171 mwStorageCallback cb, 172 gpointer data, GDestroyNotify data_free); 173 174 175 /** Initiates a store call to the storage service. If the service is 176 not currently available, the call will be cached and processed 177 when the service is started. 178 179 @param srvc the storage service 180 @param item storage unit to save 181 @param cb callback function when the load call completes 182 @param data optional user data for callback 183 @param data_free optional cleanup function for user data 184 */ 185 void mwServiceStorage_save(struct mwServiceStorage *srvc, 186 struct mwStorageUnit *item, 187 mwStorageCallback cb, 188 gpointer data, GDestroyNotify data_free); 189 190 191 #ifdef __cplusplus 192 } 193 #endif 194 195 196 #endif /* _MW_SRVC_STORE_H */ 197