Blame src/mw_srvc_store.h

Packit 16808d
Packit 16808d
/*
Packit 16808d
  Meanwhile - Unofficial Lotus Sametime Community Client Library
Packit 16808d
  Copyright (C) 2004  Christopher (siege) O'Brien
Packit 16808d
  
Packit 16808d
  This library is free software; you can redistribute it and/or
Packit 16808d
  modify it under the terms of the GNU Library General Public
Packit 16808d
  License as published by the Free Software Foundation; either
Packit 16808d
  version 2 of the License, or (at your option) any later version.
Packit 16808d
  
Packit 16808d
  This library is distributed in the hope that it will be useful,
Packit 16808d
  but WITHOUT ANY WARRANTY; without even the implied warranty of
Packit 16808d
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Packit 16808d
  Library General Public License for more details.
Packit 16808d
  
Packit 16808d
  You should have received a copy of the GNU Library General Public
Packit 16808d
  License along with this library; if not, write to the Free
Packit 16808d
  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
Packit 16808d
*/
Packit 16808d
Packit 16808d
#ifndef _MW_SRVC_STORE_H
Packit 16808d
#define _MW_SRVC_STORE_H
Packit 16808d
Packit 16808d
Packit 16808d
#include <glib.h>
Packit 16808d
#include "mw_common.h"
Packit 16808d
Packit 16808d
Packit 16808d
#ifdef __cplusplus
Packit 16808d
extern "C" {
Packit 16808d
#endif
Packit 16808d
Packit 16808d
Packit 16808d
/** Type identifier for the storage service */
Packit 16808d
#define mwService_STORAGE  0x00000018
Packit 16808d
Packit 16808d
Packit 16808d
/** @struct mwServiceStorage
Packit 16808d
    @see mwServiceStorage_new
Packit 16808d
Packit 16808d
    Instance of the storage service */
Packit 16808d
struct mwServiceStorage;
Packit 16808d
Packit 16808d
Packit 16808d
/** @struct mwStorage
Packit 16808d
Packit 16808d
    Unit Represents information intended for loading from or saving to
Packit 16808d
    the storage service */
Packit 16808d
struct mwStorageUnit;
Packit 16808d
Packit 16808d
Packit 16808d
/** The upper limit of reserved Lotus keys */
Packit 16808d
#define LOTUS_RESERVED_LIMIT  0x186a0
Packit 16808d
Packit 16808d
Packit 16808d
/** Check if a key is in the range of Lotus reserved keys */
Packit 16808d
#define KEY_IS_LOTUS_RESERVED(key) \
Packit 16808d
  (((guint32) key) <= (LOTUS_RESERVED_LIMIT))
Packit 16808d
Packit 16808d
Packit 16808d
/** Some common keys storage keys. Anything in the range 0x00 to
Packit 16808d
    0x186a0 (100000) is reserved for use by the Lotus
Packit 16808d
    clients. */
Packit 16808d
enum mwStorageKey {
Packit 16808d
Packit 16808d
  /** The buddy list, in the Sametime .dat file format. String */
Packit 16808d
  mwStore_AWARE_LIST      = 0x00000000,
Packit 16808d
Packit 16808d
  /** Default text for chat invitations. String */
Packit 16808d
  mwStore_INVITE_CHAT     = 0x00000006,
Packit 16808d
Packit 16808d
  /** Default text for meeting invitations. String */
Packit 16808d
  mwStore_INVITE_MEETING  = 0x0000000e,
Packit 16808d
Packit 16808d
  /** Last five Away messages, separated by semicolon. String */
Packit 16808d
  mwStore_AWAY_MESSAGES   = 0x00000050,
Packit 16808d
Packit 16808d
  /** Last five Busy (DND) messages, separated by semicolon. String */
Packit 16808d
  mwStore_BUSY_MESSAGES   = 0x0000005a,
Packit 16808d
Packit 16808d
  /** Last five Active messages, separated by semicolon. String */
Packit 16808d
  mwStore_ACTIVE_MESSAGES = 0x00000064,
Packit 16808d
};
Packit 16808d
Packit 16808d
Packit 16808d
/** Appropriate function type for load and store callbacks.
Packit 16808d
    @param srvc       the storage service
Packit 16808d
    @param result     the result value of the load or store call
Packit 16808d
    @param item       the storage unit loaded or saved
Packit 16808d
    @param data       optional user data
Packit 16808d
*/
Packit 16808d
typedef void (*mwStorageCallback)
Packit 16808d
     (struct mwServiceStorage *srvc,
Packit 16808d
      guint32 result, struct mwStorageUnit *item,
Packit 16808d
      gpointer data);
Packit 16808d
Packit 16808d
Packit 16808d
/** Allocates and initializes a storage service instance for use on
Packit 16808d
    the passed session. */
Packit 16808d
struct mwServiceStorage *mwServiceStorage_new(struct mwSession *);
Packit 16808d
Packit 16808d
Packit 16808d
/** create an empty storage unit */
Packit 16808d
struct mwStorageUnit *mwStorageUnit_new(guint32 key);
Packit 16808d
Packit 16808d
Packit 16808d
/** creates a storage unit with the passed key, and a copy of data. */
Packit 16808d
struct mwStorageUnit *mwStorageUnit_newOpaque(guint32 key,
Packit 16808d
					      struct mwOpaque *data);
Packit 16808d
Packit 16808d
Packit 16808d
/** creates a storage unit with the passed key, and an encapsulated
Packit 16808d
    boolean value */
Packit 16808d
struct mwStorageUnit *mwStorageUnit_newBoolean(guint32 key,
Packit 16808d
					       gboolean val);
Packit 16808d
Packit 16808d
Packit 16808d
struct mwStorageUnit *mwStorageUnit_newInteger(guint32 key,
Packit 16808d
					       guint32 val);
Packit 16808d
Packit 16808d
Packit 16808d
/** creates a storage unit with the passed key, and an encapsulated
Packit 16808d
    string value. */
Packit 16808d
struct mwStorageUnit *mwStorageUnit_newString(guint32 key,
Packit 16808d
					      const char *str);
Packit 16808d
Packit 16808d
Packit 16808d
/** get the key for the given storage unit */
Packit 16808d
guint32 mwStorageUnit_getKey(struct mwStorageUnit *);
Packit 16808d
Packit 16808d
Packit 16808d
/** attempts to obtain a boolean value from a storage unit. If the
Packit 16808d
    unit is empty, or does not contain the type in a recongnizable
Packit 16808d
    format, val is returned instead */
Packit 16808d
gboolean mwStorageUnit_asBoolean(struct mwStorageUnit *, gboolean val);
Packit 16808d
Packit 16808d
Packit 16808d
/** attempts to obtain a guint32 value from a storage unit. If the
Packit 16808d
    unit is empty, or does not contain the type in a recognizable
Packit 16808d
    format, val is returned instead */
Packit 16808d
guint32 mwStorageUnit_asInteger(struct mwStorageUnit *, guint32 val);
Packit 16808d
Packit 16808d
Packit 16808d
/** attempts to obtain a string value from a storage unit. If the unit
Packit 16808d
    is empty, or does not contain the type in a recognizable format,
Packit 16808d
    NULL is returned instead. Note that the string returned is a copy,
Packit 16808d
    and will need to be deallocated at some point. */
Packit 16808d
char *mwStorageUnit_asString(struct mwStorageUnit *);
Packit 16808d
Packit 16808d
Packit 16808d
/** direct access to the opaque data backing the storage unit */
Packit 16808d
struct mwOpaque *mwStorageUnit_asOpaque(struct mwStorageUnit *);
Packit 16808d
Packit 16808d
Packit 16808d
/** clears and frees a storage unit */
Packit 16808d
void mwStorageUnit_free(struct mwStorageUnit *);
Packit 16808d
Packit 16808d
      
Packit 16808d
/** Initiates a load call to the storage service. If the service is
Packit 16808d
    not currently available, the call will be cached and processed
Packit 16808d
    when the service is started.
Packit 16808d
Packit 16808d
    @param srvc       the storage service
Packit 16808d
    @param item       storage unit to load
Packit 16808d
    @param cb         callback function when the load call completes
Packit 16808d
    @param data       user data for callback
Packit 16808d
    @param data_free  optional cleanup function for user data
Packit 16808d
*/
Packit 16808d
void mwServiceStorage_load(struct mwServiceStorage *srvc,
Packit 16808d
			   struct mwStorageUnit *item,
Packit 16808d
			   mwStorageCallback cb,
Packit 16808d
			   gpointer data, GDestroyNotify data_free);
Packit 16808d
Packit 16808d
Packit 16808d
/** Initiates a store call to the storage service. If the service is
Packit 16808d
    not currently available, the call will be cached and processed
Packit 16808d
    when the service is started.
Packit 16808d
Packit 16808d
    @param srvc       the storage service
Packit 16808d
    @param item       storage unit to save
Packit 16808d
    @param cb         callback function when the load call completes
Packit 16808d
    @param data       optional user data for callback
Packit 16808d
    @param data_free  optional cleanup function for user data
Packit 16808d
 */
Packit 16808d
void mwServiceStorage_save(struct mwServiceStorage *srvc,
Packit 16808d
			   struct mwStorageUnit *item,
Packit 16808d
			   mwStorageCallback cb,
Packit 16808d
			   gpointer data, GDestroyNotify data_free);
Packit 16808d
Packit 16808d
Packit 16808d
#ifdef __cplusplus
Packit 16808d
}
Packit 16808d
#endif
Packit 16808d
Packit 16808d
Packit 16808d
#endif /* _MW_SRVC_STORE_H */