Blame src/mw_srvc_store.h

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