view src/protocols/sametime/meanwhile/mw_srvc_store.h @ 11943:0110fc7c6a8a

[gaim-migrate @ 14234] Bringing things up to date with the last Meanwhile release, 0.5.0 and the last gaim-meanwhile plugin release, 1.2.5 (which should be the last plugin release against oldstatus, if all goes well with HEAD and no major bugs crop up) It builds, so that's a start. The status bits that have been empty since the first import of the sametime stuff are still empty, but I'm going to try and fill those in tomorrow. I've decided to try and start using HEAD actively, to encourage me to get this freaking prpl fully functional. committer: Tailor Script <[e-mail]>

/*
  Meanwhile - Unofficial Lotus Sametime Community Client Library
  Copyright (C) 2004  Christopher (siege) O'Brien
  
  This library is free software; you can redistribute it and/or
  modify it under the terms of the GNU Library General Public
  License as published by the Free Software Foundation; either
  version 2 of the License, or (at your option) any later version.
  
  This library is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  Library General Public License for more details.
  
  You should have received a copy of the GNU Library General Public
  License along with this library; if not, write to the Free
  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
*/

#ifndef _MW_SRVC_STORE_H
#define _MW_SRVC_STORE_H


#include <glib.h>
#include "mw_common.h"


/** Type identifier for the storage service */
#define mwService_STORAGE  0x00000018


/** @struct mwServiceStorage
    @see mwServiceStorage_new

    Instance of the storage service */
struct mwServiceStorage;


/** @struct mwStorage

    Unit Represents information intended for loading from or saving to
    the storage service */
struct mwStorageUnit;


/** The upper limit of reserved Lotus keys */
#define LOTUS_RESERVED_LIMIT  0x186a0


/** Check if a key is in the range of Lotus reserved keys */
#define KEY_IS_LOTUS_RESERVED(key) \
  (((guint32) key) <= (LOTUS_RESERVED_LIMIT))


/** Some common keys storage keys. Anything in the range 0x00 to
    0x186a0 (100000) is reserved for use by the Lotus
    clients. */
enum mwStorageKey {

  /** The buddy list, in the Sametime .dat file format. String */
  mwStore_AWARE_LIST      = 0x00000000,

  /** Default text for chat invitations. String */
  mwStore_INVITE_CHAT     = 0x00000006,

  /** Default text for meeting invitations. String */
  mwStore_INVITE_MEETING  = 0x0000000e,

  /** Last five Away messages, separated by semicolon. String */
  mwStore_AWAY_MESSAGES   = 0x00000050,

  /** Last five Busy (DND) messages, separated by semicolon. String */
  mwStore_BUSY_MESSAGES   = 0x0000005a,

  /** Last five Active messages, separated by semicolon. String */
  mwStore_ACTIVE_MESSAGES = 0x00000064,
};


/** Appropriate function type for load and store callbacks.
    @param srvc       the storage service
    @param result     the result value of the load or store call
    @param item       the storage unit loaded or saved
    @param data       optional user data
*/
typedef void (*mwStorageCallback)
     (struct mwServiceStorage *srvc,
      guint32 result, struct mwStorageUnit *item,
      gpointer data);


/** Allocates and initializes a storage service instance for use on
    the passed session. */
struct mwServiceStorage *mwServiceStorage_new(struct mwSession *);


/** create an empty storage unit */
struct mwStorageUnit *mwStorageUnit_new(guint32 key);


/** creates a storage unit with the passed key, and a copy of data. */
struct mwStorageUnit *mwStorageUnit_newOpaque(guint32 key,
					      struct mwOpaque *data);


/** creates a storage unit with the passed key, and an encapsulated
    boolean value */
struct mwStorageUnit *mwStorageUnit_newBoolean(guint32 key,
					       gboolean val);


struct mwStorageUnit *mwStorageUnit_newInteger(guint32 key,
					       guint32 val);


/** creates a storage unit with the passed key, and an encapsulated
    string value. */
struct mwStorageUnit *mwStorageUnit_newString(guint32 key,
					      const char *str);


/** get the key for the given storage unit */
guint32 mwStorageUnit_getKey(struct mwStorageUnit *);


/** attempts to obtain a boolean value from a storage unit. If the
    unit is empty, or does not contain the type in a recongnizable
    format, val is returned instead */
gboolean mwStorageUnit_asBoolean(struct mwStorageUnit *, gboolean val);


/** attempts to obtain a guint32 value from a storage unit. If the
    unit is empty, or does not contain the type in a recognizable
    format, val is returned instead */
guint32 mwStorageUnit_asInteger(struct mwStorageUnit *, guint32 val);


/** attempts to obtain a string value from a storage unit. If the unit
    is empty, or does not contain the type in a recognizable format,
    NULL is returned instead. Note that the string returned is a copy,
    and will need to be deallocated at some point. */
char *mwStorageUnit_asString(struct mwStorageUnit *);


/** direct access to the opaque data backing the storage unit */
struct mwOpaque *mwStorageUnit_asOpaque(struct mwStorageUnit *);


/** clears and frees a storage unit */
void mwStorageUnit_free(struct mwStorageUnit *);

      
/** Initiates a load call to the storage service. If the service is
    not currently available, the call will be cached and processed
    when the service is started.

    @param srvc       the storage service
    @param item       storage unit to load
    @param cb         callback function when the load call completes
    @param data       user data for callback
    @param data_free  optional cleanup function for user data
*/
void mwServiceStorage_load(struct mwServiceStorage *srvc,
			   struct mwStorageUnit *item,
			   mwStorageCallback cb,
			   gpointer data, GDestroyNotify data_free);


/** Initiates a store call to the storage service. If the service is
    not currently available, the call will be cached and processed
    when the service is started.

    @param srvc       the storage service
    @param item       storage unit to save
    @param cb         callback function when the load call completes
    @param data       optional user data for callback
    @param data_free  optional cleanup function for user data
 */
void mwServiceStorage_save(struct mwServiceStorage *srvc,
			   struct mwStorageUnit *item,
			   mwStorageCallback cb,
			   gpointer data, GDestroyNotify data_free);


#endif