Blame src/mw_common.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_COMMON_H
Packit 16808d
#define _MW_COMMON_H
Packit 16808d
Packit 16808d
Packit 16808d
/** @file mw_common.h
Packit 16808d
Packit 16808d
    Common data types and functions for handling those types.
Packit 16808d
Packit 16808d
    Functions in this file all fit into similar naming conventions of
Packit 16808d
    TYPE_ACTION as per the activity they perform. The
Packit 16808d
    following actions are available:
Packit 16808d
Packit 16808d
    void TYPE_put(struct mwPutBuffer *b, TYPE *val)
Packit 16808d
    - marshalls val onto the buffer b. The buffer will grow as necessary
Packit 16808d
    to fit all the data put into it. For guint16, guint32, and
Packit 16808d
    gboolean, TYPE val is used instead of TYPE
Packit 16808d
    \*val.
Packit 16808d
Packit 16808d
    void TYPE_get(struct mwGetBuffer *b, TYPE *val)
Packit 16808d
    - unmarshals val from the buffer b. Failure (due to lack of
Packit 16808d
    insufficient remaining buffer) is indicated in the buffer's error
Packit 16808d
    field. A call to a _get function with a buffer in an error state
Packit 16808d
    has to effect.
Packit 16808d
Packit 16808d
    void TYPE_clear(TYPE *val)
Packit 16808d
    - zeros and frees internal members of val, but does not free val
Packit 16808d
    itself. Needs to be called before free-ing any complex types which
Packit 16808d
    have been unmarshalled from a TYPE_get or populated from a
Packit 16808d
    TYPE_clone call to prevent memory leaks.
Packit 16808d
Packit 16808d
    void TYPE_clone(TYPE *to, TYPE *from)
Packit 16808d
    - copies/clones members of from into to. May result in memory
Packit 16808d
    allocation for some types. Note that to is not cleared
Packit 16808d
    before-hand, it must already be in a pristine condition.
Packit 16808d
Packit 16808d
    gboolean TYPE_equal(TYPE *y, TYPE *z)
Packit 16808d
    - simple equality test.
Packit 16808d
*/
Packit 16808d
Packit 16808d
Packit 16808d
#include <glib.h>
Packit 16808d
Packit 16808d
Packit 16808d
#ifdef __cplusplus
Packit 16808d
extern "C" {
Packit 16808d
#endif
Packit 16808d
Packit 16808d
Packit 16808d
/** @struct mwPutBuffer
Packit 16808d
    buffer to be written to */
Packit 16808d
struct mwPutBuffer;
Packit 16808d
Packit 16808d
/** @struct mwGetBuffer
Packit 16808d
    buffer to be read from */
Packit 16808d
struct mwGetBuffer;
Packit 16808d
Packit 16808d
Packit 16808d
/** A length of binary data, not null-terminated. */
Packit 16808d
struct mwOpaque {
Packit 16808d
  gsize len;     /**< length of data. */
Packit 16808d
  guchar *data;  /**< data, normally with no NULL termination */
Packit 16808d
};
Packit 16808d
Packit 16808d
Packit 16808d
/* 8.3.6 Login Types */
Packit 16808d
Packit 16808d
/** The type of login. Normally meaning the type of client code being
Packit 16808d
    used to login with.
Packit 16808d
Packit 16808d
    If you know of any additional client identifiers, please add them
Packit 16808d
    below or submit an RFE to the meanwhile tracker.
Packit 16808d
*/
Packit 16808d
enum mwLoginType {
Packit 16808d
  mwLogin_LIB           = 0x1000,  /**< official Lotus binary library */
Packit 16808d
  mwLogin_JAVA_WEB      = 0x1001,  /**< official Lotus Java applet */
Packit 16808d
  mwLogin_BINARY        = 0x1002,  /**< official Lotus binary application */
Packit 16808d
  mwLogin_JAVA_APP      = 0x1003,  /**< official Lotus Java application */
Packit 16808d
  mwLogin_LINKS         = 0x100a,  /**< official Sametime Links toolkit */
Packit 16808d
Packit 16808d
  /* now we're getting crazy */
Packit 16808d
  mwLogin_NOTES_6_5        = 0x1200,
Packit 16808d
  mwLogin_NOTES_6_5_3      = 0x1203,
Packit 16808d
  mwLogin_NOTES_7_0_beta   = 0x1210,
Packit 16808d
  mwLogin_NOTES_7_0        = 0x1214,
Packit 16808d
  mwLogin_ICT              = 0x1300,
Packit 16808d
  mwLogin_ICT_1_7_8_2      = 0x1302,
Packit 16808d
  mwLogin_ICT_SIP          = 0x1303,
Packit 16808d
  mwLogin_NOTESBUDDY_4_14  = 0x1400,  /**< 0xff00 mask? */
Packit 16808d
  mwLogin_NOTESBUDDY_4_15  = 0x1405,
Packit 16808d
  mwLogin_NOTESBUDDY_4_16  = 0x1406,
Packit 16808d
  mwLogin_SANITY           = 0x1600,
Packit 16808d
  mwLogin_ST_PERL          = 0x1625,
Packit 16808d
  mwLogin_PMR_ALERT        = 0x1650,
Packit 16808d
  mwLogin_TRILLIAN         = 0x16aa,  /**< http://sf.net/st-plugin/ */
Packit 16808d
  mwLogin_TRILLIAN_IBM     = 0x16bb,
Packit 16808d
  mwLogin_MEANWHILE        = 0x1700,  /**< Meanwhile library */
Packit 16808d
};
Packit 16808d
Packit 16808d
Packit 16808d
/* 8.2 Common Structures */
Packit 16808d
/* 8.2.1 Login Info block */
Packit 16808d
Packit 16808d
struct mwLoginInfo {
Packit 16808d
  char *login_id;   /**< community-unique ID of the login */
Packit 16808d
  guint16 type;     /**< @see mwLoginType */
Packit 16808d
  char *user_id;    /**< community-unique ID of the user */
Packit 16808d
  char *user_name;  /**< name of user (nick name, full name, etc) */
Packit 16808d
  char *community;  /**< community name (usually domain name) */
Packit 16808d
  gboolean full;    /**< if FALSE, following fields non-existant */
Packit 16808d
  char *desc;       /**< implementation defined description */
Packit 16808d
  guint32 ip_addr;  /**< ip addr of the login */
Packit 16808d
  char *server_id;  /**< unique ID of login's server */
Packit 16808d
};
Packit 16808d
Packit 16808d
Packit 16808d
/* 8.2.2 Private Info Block */
Packit 16808d
Packit 16808d
struct mwUserItem {
Packit 16808d
  gboolean full;    /**< if FALSE, don't include name */
Packit 16808d
  char *id;         /**< user id */
Packit 16808d
  char *community;  /**< community */
Packit 16808d
  char *name;       /**< user name */
Packit 16808d
};
Packit 16808d
Packit 16808d
Packit 16808d
struct mwPrivacyInfo {
Packit 16808d
  gboolean deny;             /**< deny (true) or allow (false) users */
Packit 16808d
  guint32 count;             /**< count of users */
Packit 16808d
  struct mwUserItem *users;  /**< the users list */
Packit 16808d
};
Packit 16808d
Packit 16808d
Packit 16808d
/* 8.3.5 User Status Types */
Packit 16808d
Packit 16808d
enum mwStatusType {
Packit 16808d
  mwStatus_OFFLINE = 0x0000,
Packit 16808d
Packit 16808d
  mwStatus_ACTIVE  = 0x0020,
Packit 16808d
  mwStatus_IDLE    = 0x0040,
Packit 16808d
  mwStatus_AWAY    = 0x0060,
Packit 16808d
  mwStatus_BUSY    = 0x0080,
Packit 16808d
Packit 16808d
  mwStatus_MASK_MOBILE = 0x0200,
Packit 16808d
};
Packit 16808d
Packit 16808d
Packit 16808d
/* 8.2.3 User Status Block */
Packit 16808d
Packit 16808d
struct mwUserStatus {
Packit 16808d
  guint16 status;  /**< @see mwStatusType */
Packit 16808d
  guint32 time;    /**< last status change time in seconds */
Packit 16808d
  char *desc;      /**< status description */
Packit 16808d
};
Packit 16808d
Packit 16808d
Packit 16808d
/* 8.2.4 ID Block */
Packit 16808d
Packit 16808d
struct mwIdBlock {
Packit 16808d
  char *user;       /**< user id (login id or empty for some services) */
Packit 16808d
  char *community;  /**< community id (NULL for same community) */
Packit 16808d
};
Packit 16808d
Packit 16808d
Packit 16808d
/* 8.3.8.2 Awareness Presence Types */
Packit 16808d
Packit 16808d
/* @todo move mwAwareType, mwAwareIdBlock and mwAwareSnapshot into the
Packit 16808d
   aware service and out of common */
Packit 16808d
Packit 16808d
/** type codes for mwAwareIdBlock */
Packit 16808d
enum mwAwareType {
Packit 16808d
  mwAware_USER    = 0x0002,  /**< a single user */
Packit 16808d
  mwAware_GROUP   = 0x0003,  /**< a group */
Packit 16808d
  mwAware_SERVER  = 0x0008,  /**< a server */
Packit 16808d
};
Packit 16808d
Packit 16808d
Packit 16808d
/* 8.4.2 Awareness Messages */
Packit 16808d
/* 8.4.2.1 Awareness ID Block */
Packit 16808d
Packit 16808d
struct mwAwareIdBlock {
Packit 16808d
  guint16 type;     /**< @see mwAwareType */
Packit 16808d
  char *user;       /**< user id */
Packit 16808d
  char *community;  /**< community id (NULL for same community) */
Packit 16808d
};
Packit 16808d
Packit 16808d
Packit 16808d
/* 8.4.2.4 Snapshot */
Packit 16808d
Packit 16808d
struct mwAwareSnapshot {
Packit 16808d
  struct mwAwareIdBlock id;
Packit 16808d
  char *group;                 /**< group this id belongs to */
Packit 16808d
  gboolean online;             /**< is this user online? */
Packit 16808d
  char *alt_id;                /**< alternate ID, often same as id.user */
Packit 16808d
  struct mwUserStatus status;  /**< status of this user */
Packit 16808d
  char *name;                  /**< Formatted version of ID */
Packit 16808d
};
Packit 16808d
Packit 16808d
Packit 16808d
/** encryption blocks */
Packit 16808d
struct mwEncryptItem {
Packit 16808d
  guint16 id;            /**< cipher identifier */
Packit 16808d
  struct mwOpaque info;  /**< cipher information */
Packit 16808d
};
Packit 16808d
Packit 16808d
Packit 16808d
/** @name buffer utility functions */
Packit 16808d
/*@{*/
Packit 16808d
Packit 16808d
Packit 16808d
/** allocate a new empty buffer */
Packit 16808d
struct mwPutBuffer *mwPutBuffer_new(void);
Packit 16808d
Packit 16808d
Packit 16808d
/** write raw data to the put buffer */
Packit 16808d
void mwPutBuffer_write(struct mwPutBuffer *b, gpointer data, gsize len);
Packit 16808d
Packit 16808d
Packit 16808d
/** destroy the buffer */
Packit 16808d
void mwPutBuffer_free(struct mwPutBuffer *b);
Packit 16808d
Packit 16808d
Packit 16808d
/** move the buffer's data into an opaque, destroy the buffer */
Packit 16808d
void mwPutBuffer_finalize(struct mwOpaque *to, struct mwPutBuffer *from);
Packit 16808d
Packit 16808d
Packit 16808d
/** allocate a new buffer with a copy of the given data */
Packit 16808d
struct mwGetBuffer *mwGetBuffer_new(struct mwOpaque *data);
Packit 16808d
Packit 16808d
Packit 16808d
/** read len bytes of raw data from the get buffer into mem. If len is
Packit 16808d
    greater than the count of bytes remaining in the buffer, the
Packit 16808d
    buffer's error flag will NOT be set.
Packit 16808d
Packit 16808d
    @returns count of bytes successfully copied to mem */
Packit 16808d
gsize mwGetBuffer_read(struct mwGetBuffer *b, gpointer mem, gsize len);
Packit 16808d
Packit 16808d
Packit 16808d
/** skip len bytes in the get buffer. If len is greater than the count
Packit 16808d
    of bytes remaining in the buffer, the buffer's error flag will NOT
Packit 16808d
    be set.
Packit 16808d
Packit 16808d
    @returns count of bytes successfully skipped */
Packit 16808d
gsize mwGetBuffer_advance(struct mwGetBuffer *b, gsize len);
Packit 16808d
Packit 16808d
Packit 16808d
/** allocate a new buffer backed by the given data. Calling
Packit 16808d
    mwGetBuffer_free will not result in the underlying data being
Packit 16808d
    freed */
Packit 16808d
struct mwGetBuffer *mwGetBuffer_wrap(const struct mwOpaque *data);
Packit 16808d
Packit 16808d
Packit 16808d
/** destroy the buffer */
Packit 16808d
void mwGetBuffer_free(struct mwGetBuffer *b);
Packit 16808d
Packit 16808d
Packit 16808d
/** reset the buffer to the very beginning. Also clears the buffer's
Packit 16808d
    error flag. */
Packit 16808d
void mwGetBuffer_reset(struct mwGetBuffer *b);
Packit 16808d
Packit 16808d
Packit 16808d
/** count of remaining available bytes */
Packit 16808d
gsize mwGetBuffer_remaining(struct mwGetBuffer *b);
Packit 16808d
Packit 16808d
Packit 16808d
/** TRUE if an error occurred while reading a basic type from this
Packit 16808d
    buffer */
Packit 16808d
gboolean mwGetBuffer_error(struct mwGetBuffer *b);
Packit 16808d
Packit 16808d
Packit 16808d
/*@}*/
Packit 16808d
Packit 16808d
Packit 16808d
/** @name Basic Data Types
Packit 16808d
    The basic types are combined to construct the compound types.
Packit 16808d
 */
Packit 16808d
/*@{*/
Packit 16808d
Packit 16808d
Packit 16808d
void guint16_put(struct mwPutBuffer *b, guint16 val);
Packit 16808d
Packit 16808d
void guint16_get(struct mwGetBuffer *b, guint16 *val);
Packit 16808d
Packit 16808d
guint16 guint16_peek(struct mwGetBuffer *b);
Packit 16808d
Packit 16808d
Packit 16808d
void guint32_put(struct mwPutBuffer *b, guint32 val);
Packit 16808d
Packit 16808d
void guint32_get(struct mwGetBuffer *b, guint32 *val);
Packit 16808d
Packit 16808d
guint32 guint32_peek(struct mwGetBuffer *b);
Packit 16808d
Packit 16808d
Packit 16808d
void gboolean_put(struct mwPutBuffer *b, gboolean val);
Packit 16808d
Packit 16808d
void gboolean_get(struct mwGetBuffer *b, gboolean *val);
Packit 16808d
Packit 16808d
gboolean gboolean_peek(struct mwGetBuffer *b);
Packit 16808d
Packit 16808d
Packit 16808d
void mwString_put(struct mwPutBuffer *b, const char *str);
Packit 16808d
Packit 16808d
void mwString_get(struct mwGetBuffer *b, char **str);
Packit 16808d
Packit 16808d
Packit 16808d
void mwOpaque_put(struct mwPutBuffer *b, const struct mwOpaque *o);
Packit 16808d
Packit 16808d
void mwOpaque_get(struct mwGetBuffer *b, struct mwOpaque *o);
Packit 16808d
Packit 16808d
void mwOpaque_clear(struct mwOpaque *o);
Packit 16808d
Packit 16808d
void mwOpaque_free(struct mwOpaque *o);
Packit 16808d
Packit 16808d
void mwOpaque_clone(struct mwOpaque *to, const struct mwOpaque *from);
Packit 16808d
Packit 16808d
Packit 16808d
/*@}*/
Packit 16808d
Packit 16808d
Packit 16808d
/** @name Compound Data Types */
Packit 16808d
/*@{*/
Packit 16808d
Packit 16808d
Packit 16808d
void mwLoginInfo_put(struct mwPutBuffer *b, const struct mwLoginInfo *info);
Packit 16808d
Packit 16808d
void mwLoginInfo_get(struct mwGetBuffer *b, struct mwLoginInfo *info);
Packit 16808d
Packit 16808d
void mwLoginInfo_clear(struct mwLoginInfo *info);
Packit 16808d
Packit 16808d
void mwLoginInfo_clone(struct mwLoginInfo *to, const struct mwLoginInfo *from);
Packit 16808d
Packit 16808d
Packit 16808d
void mwUserItem_put(struct mwPutBuffer *b, const struct mwUserItem *user);
Packit 16808d
Packit 16808d
void mwUserItem_get(struct mwGetBuffer *b, struct mwUserItem *user);
Packit 16808d
Packit 16808d
void mwUserItem_clear(struct mwUserItem *user);
Packit 16808d
Packit 16808d
void mwUserItem_clone(struct mwUserItem *to, const struct mwUserItem *from);
Packit 16808d
Packit 16808d
Packit 16808d
void mwPrivacyInfo_put(struct mwPutBuffer *b,
Packit 16808d
		       const struct mwPrivacyInfo *info);
Packit 16808d
Packit 16808d
void mwPrivacyInfo_get(struct mwGetBuffer *b, struct mwPrivacyInfo *info);
Packit 16808d
Packit 16808d
void mwPrivacyInfo_clear(struct mwPrivacyInfo *info);
Packit 16808d
Packit 16808d
void mwPrivacyInfo_clone(struct mwPrivacyInfo *to,
Packit 16808d
			 const struct mwPrivacyInfo *from);
Packit 16808d
Packit 16808d
Packit 16808d
void mwUserStatus_put(struct mwPutBuffer *b,
Packit 16808d
		      const struct mwUserStatus *stat);
Packit 16808d
Packit 16808d
void mwUserStatus_get(struct mwGetBuffer *b, struct mwUserStatus *stat);
Packit 16808d
Packit 16808d
void mwUserStatus_clear(struct mwUserStatus *stat);
Packit 16808d
Packit 16808d
void mwUserStatus_clone(struct mwUserStatus *to,
Packit 16808d
			const struct mwUserStatus *from);
Packit 16808d
Packit 16808d
Packit 16808d
void mwIdBlock_put(struct mwPutBuffer *b, const struct mwIdBlock *id);
Packit 16808d
Packit 16808d
void mwIdBlock_get(struct mwGetBuffer *b, struct mwIdBlock *id);
Packit 16808d
Packit 16808d
void mwIdBlock_clear(struct mwIdBlock *id);
Packit 16808d
Packit 16808d
void mwIdBlock_clone(struct mwIdBlock *to,
Packit 16808d
		     const struct mwIdBlock *from);
Packit 16808d
Packit 16808d
guint mwIdBlock_hash(const struct mwIdBlock *idb);
Packit 16808d
Packit 16808d
gboolean mwIdBlock_equal(const struct mwIdBlock *a,
Packit 16808d
			 const struct mwIdBlock *b);
Packit 16808d
Packit 16808d
Packit 16808d
void mwAwareIdBlock_put(struct mwPutBuffer *b,
Packit 16808d
			const struct mwAwareIdBlock *idb);
Packit 16808d
Packit 16808d
void mwAwareIdBlock_get(struct mwGetBuffer *b, struct mwAwareIdBlock *idb);
Packit 16808d
Packit 16808d
void mwAwareIdBlock_clear(struct mwAwareIdBlock *idb);
Packit 16808d
Packit 16808d
void mwAwareIdBlock_clone(struct mwAwareIdBlock *to,
Packit 16808d
			  const struct mwAwareIdBlock *from);
Packit 16808d
Packit 16808d
guint mwAwareIdBlock_hash(const struct mwAwareIdBlock *a);
Packit 16808d
Packit 16808d
gboolean mwAwareIdBlock_equal(const struct mwAwareIdBlock *a,
Packit 16808d
			      const struct mwAwareIdBlock *b);
Packit 16808d
Packit 16808d
Packit 16808d
void mwAwareSnapshot_get(struct mwGetBuffer *b,
Packit 16808d
			 struct mwAwareSnapshot *idb);
Packit 16808d
Packit 16808d
void mwAwareSnapshot_clear(struct mwAwareSnapshot *idb);
Packit 16808d
Packit 16808d
void mwAwareSnapshot_clone(struct mwAwareSnapshot *to,
Packit 16808d
			   const struct mwAwareSnapshot *from);
Packit 16808d
Packit 16808d
Packit 16808d
void mwEncryptItem_put(struct mwPutBuffer *b,
Packit 16808d
		       const struct mwEncryptItem *item);
Packit 16808d
Packit 16808d
void mwEncryptItem_get(struct mwGetBuffer *b, struct mwEncryptItem *item);
Packit 16808d
Packit 16808d
void mwEncryptItem_clear(struct mwEncryptItem *item);
Packit 16808d
Packit 16808d
void mwEncryptItem_free(struct mwEncryptItem *item);
Packit 16808d
Packit 16808d
Packit 16808d
/*@}*/
Packit 16808d
Packit 16808d
Packit 16808d
#ifdef __cplusplus
Packit 16808d
}
Packit 16808d
#endif
Packit 16808d
Packit 16808d
Packit 16808d
#endif /* _MW_COMMON_H */