annotate src/protocols/novell/nmevent.h @ 8675:9ee2542d1104

[gaim-migrate @ 9428] A GroupWise plugin from Novell. committer: Tailor Script <[e-mail]>

/*
 * nmevent.h
 *
 * Copyright © 2004 Unpublished Work of Novell, Inc. All Rights Reserved.
 *
 * THIS WORK IS AN UNPUBLISHED WORK OF NOVELL, INC. NO PART OF THIS WORK MAY BE
 * USED, PRACTICED, PERFORMED, COPIED, DISTRIBUTED, REVISED, MODIFIED,
 * TRANSLATED, ABRIDGED, CONDENSED, EXPANDED, COLLECTED, COMPILED, LINKED,
 * RECAST, TRANSFORMED OR ADAPTED WITHOUT THE PRIOR WRITTEN CONSENT OF NOVELL,
 * INC. ANY USE OR EXPLOITATION OF THIS WORK WITHOUT AUTHORIZATION COULD SUBJECT
 * THE PERPETRATOR TO CRIMINAL AND CIVIL LIABILITY.
 * 
 * AS BETWEEN [GAIM] AND NOVELL, NOVELL GRANTS [GAIM] THE RIGHT TO REPUBLISH
 * THIS WORK UNDER THE GPL (GNU GENERAL PUBLIC LICENSE) WITH ALL RIGHTS AND
 * LICENSES THEREUNDER.  IF YOU HAVE RECEIVED THIS WORK DIRECTLY OR INDIRECTLY
 * FROM [GAIM] AS PART OF SUCH A REPUBLICATION, YOU HAVE ALL RIGHTS AND LICENSES
 * GRANTED BY [GAIM] UNDER THE GPL.  IN CONNECTION WITH SUCH A REPUBLICATION, IF
 * ANYTHING IN THIS NOTICE CONFLICTS WITH THE TERMS OF THE GPL, SUCH TERMS
 * PREVAIL.
 *
 */

#ifndef __NM_EVENT_H__
#define __NM_EVENT_H__

typedef struct _NMEvent NMEvent;

#include "nmuser.h"

/**
 * Defines for the event types 
 */
#define	NMEVT_INVALID_RECIPIENT			101
#define	NMEVT_UNDELIVERABLE_STATUS		102
#define	NMEVT_STATUS_CHANGE				103
#define	NMEVT_CONTACT_ADD				104
#define	NMEVT_CONFERENCE_CLOSED			105
#define	NMEVT_CONFERENCE_JOINED			106
#define	NMEVT_CONFERENCE_LEFT			107
#define	NMEVT_RECEIVE_MESSAGE			108
#define	NMEVT_RECEIVE_FILE				109
#define NMEVT_USER_TYPING				112
#define NMEVT_USER_NOT_TYPING			113
#define NMEVT_USER_DISCONNECT			114
#define NMEVT_SERVER_DISCONNECT			115
#define NMEVT_CONFERENCE_RENAME			116
#define NMEVT_CONFERENCE_INVITE			117
#define NMEVT_CONFERENCE_INVITE_NOTIFY	118
#define NMEVT_CONFERENCE_REJECT			119
#define NMEVT_RECEIVE_AUTOREPLY			121
#define NMEVT_START						NMEVT_INVALID_RECIPIENT
#define NMEVT_STOP						NMEVT_RECEIVE_AUTOREPLY

/**
 * Process the event. The event will be read, an NMEvent will
 * be created, and the event callback will be called.
 *
 * @param user		The main user structure.
 * @param type		The type of the event to read.
 *
 * @return			NM_OK on success
 */
NMERR_T nm_process_event(NMUser * user, int type);

/**
 * Creates an NMEvent
 *
 * The NMEvent should be released by calling
 * nm_release_event.
 *
 * @param type		The event type, see defines above.
 * @param source	The DN of the event source.
 * @param gmt		The time that the event occurred.
 *
 * @return 			The new NMEvent
 */
NMEvent *nm_create_event(int type, const char *source, guint32 gmt);

/**
 * Releases an NMEvent
 *
 * @param event		The event to release
 *
 */
void nm_release_event(NMEvent * event);

/**
 * Sets the conference object for the given event.
 *
 * @param event			The event.
 * @param conference	The conference to associate with the event.
 *
 */
void nm_event_set_conference(NMEvent * event, NMConference * conference);

/**
 * Returns the conference object associated with the given event. This should not
 * be released. If it needs to be kept around call nm_conference_addref().
 *
 * @param event	The event.
 *
 * @return		The conference associated with the event, or NULL
 *				if no conference has been set for the event.
 */
NMConference *nm_event_get_conference(NMEvent * event);

/**
 * Sets the NMUserRecord object for the given event.
 * The user record represents the event source.
 *
 * @param event			The event.
 * @param user_record	The user record to associate with the event.
 *
 */
void nm_event_set_user_record(NMEvent * event, NMUserRecord * user_record);

/**
 * Returns the NMUserRecord object associated with the given event. 
 * The user record represents the event source. This should not
 * be released. If it needs to be kept around call
 * nm_user_record_add_ref().
 *
 * @param event	The event.
 *
 * @return		The user record associated with the event, or NULL
 *				if no user record has been set for the event.
 */
NMUserRecord *nm_event_get_user_record(NMEvent * event);

/**
 * Sets the text to associate with the given event.
 *
 * @param event	The event.
 * @param text	The text to associate with the event.
 *
 */
void nm_event_set_text(NMEvent * event, const char *text);

/**
 * Returns the text associated with the given event.
 *
 * @param event	The event.
 *
 * @return		The text associated with the event, or NULL
 *				if no text has been set for the event.
 */
const char *nm_event_get_text(NMEvent * event);

/**
 * Returns the source of the event (this will be the full DN of the
 * event source).
 *
 * @param event	The event.
 *
 * @return		The full DN of the event's source.
 */
const char *nm_event_get_source(NMEvent * event);

/**
 * Returns the type of the event. See the defines above for
 * a list of possible event types.
 *
 * @param event	The event.
 *
 * @return		The type of the event.
 *
 */
int nm_event_get_type(NMEvent * event);

/**
 * Returns the time that the event took place.
 *
 * @param event	The event.
 *
 * @return		The timestamp for the event. This is the number of
 *			    seconds since 1/1/1970 (as returned by the time() 
 *				system call).
 */
guint32 nm_event_get_gmt(NMEvent * event);

#endif