libfetion.h

linux-下的fetion-0.8.1。包括所有源代码

/**
 * \file libfetion.h
 * \author dengdd <[e-mail]>
 * \date 2008/1/1
 * 
 * This file includes necessary interfaces of libfetion.
 *
 \verbatim

    Copyright (C) 2008 dengdd.

    All rights reserved by dengdd.

    This file is part of libfetion, a cross-operating-system library to operate China mobile's fetion IM.

 \endverbatim
 */

#ifndef _LIB_FETION_H
#define _LIB_FETION_H

#ifdef __LIBFETION_LIB__
#include "common.h"
#include "event.h"
#else
#include "libfetion/common.h"
#include "libfetion/event.h"
#include "libfetion/datastruct.h"
#endif

#ifdef __cplusplus 
extern "C" {
#endif

/**
 * \defgroup libfetion  LibFetion Functions
 * @{
 */

	/**
	 * \defgroup init_libfetion  LibFetion Init
	 * @{
	 */
	/** @} end of init_libfetion */

	/**
	 * \defgroup fetion_login  Login and Out
	 * @{
	 */
		/**
		 * \defgroup  simple_fetion_login  Simple Login function
		 * @{
		*/
		/** @} end of simple_fetion_login*/
		/**
		* \defgroup  generic_fetion_login_functions  Generic Login function
		* @{
		*/
		/** @} end of generic_fetion_login_functions */
	/** @} end of fetion_login */

	/**
	 * \defgroup  system_msg_cb  Set System Message CallBack Functions
	 * @{
	 */
	/** @} end of system_msg_cb */

	/**
	 * \defgroup fetion_receive  Receive message Functions
	 * @{
	 */
	/** @} end of fetion_receive */

	/**
	 * \defgroup fetion_send_sms  Send SMS Functions
	 * @{
	 */
		/**
		* \defgroup simple_send_sms_functions  Simple SendSms functions
		* @{
		*/
		/** @} end of simple_send_sms_functions */

		/**
		 * \defgroup generic_send_sms_functions  Generic SendSMS functions
		 * @{
		*/
		/** @} end of generic_send_sms_functions */
	/** @} end of fetion_send_sms */

	/**
	 * \defgroup send_dialog_fetion_functions  Dialog Message 
	 * @{
	 */

		/**
		 * \defgroup simple_send_dialog_fetion_functions  Simple Dialog Message 
		 * @{
		*/
		/** @} end of simple_send_dialog_fetion_functions */

		/**
		* \defgroup generic_send_dialog_fetion_functions  Generic Dialog Message 
		* @{
		*/
		/** @} end of generic_send_dialog_fetion_functions */
	/** @} end of send_dialog_fetion_functions */

	/**
	 * \defgroup get_or_set_user_info  Get Or Set User Info
	 * @{
	 */
	/** @} end of get_or_set_user_info */

	/**
	 * \defgroup get_contact_info  Get Contacts info
	 * @{
	 */
	/** @} end of get_contact_info */

	/**
	 * \defgroup fetion_group_opt  Group Opt Functions
	 * @{
	 */

		/**
		 * \defgroup simple_fetion_group_opt  Simple Group Opt Functions
		 * @{
		 */
		/** @} end of simple_fetion_group_opt */

		/**
		 * \defgroup generic_fetion_group_opt  Generic Group Opt Functions
		 * @{
		 */
		/** @} end of generic_fetion_group_opt */

	/** @} end of fetion_group_opt */

	/**
	 * \defgroup fetion_buddy_opt  Buddy Opt Functions
	 * @{
	 */

		/**
		 * \defgroup simple_fetion_buddy_opt  Simple Buddy Opt Functions
		 * @{
		 */
		/** @} end of simple_fetion_buddy_opt */

		/**
		* \defgroup generic_fetion_buddy_opt  Generic Buddy Opt Functions
		* @{
		*/
		/** @} end of generic_fetion_buddy_opt */

	/** @} end of fetion_buddy_opt */

	/**
	 * \defgroup fetion_ext  Extend Functions
	 * @{
	 */
	/** @} end of fetion_ext */


	/**
	 * \defgroup fetion_misc  Misc Functions
	 * @{
	 */
	/** @} end of fetion_misc */


/** @} end of libfetion */

/**
 * \addtogroup init_libfetion
 * @{
 */
/**
  * \fn BOOL fx_init(void)
  * \brief if you want to use the libfetion, you must invoke this functions at first.
  *
  * This function will init some resources which the libfetion needed.
  *
  * \return TRUE if init successfully, otherwise return FALSE.
  *
  * \sa fx_shutdown
*/
FX_EXPORT BOOL fx_init(void);

/**
  * \fn void fx_terminate(void)
  * \brief shutdown the libfetion, when libfetion isn't used any more.
  *
  * This function will release the resources which the libfetion used.
  *
  * \sa fx_init
*/
FX_EXPORT void fx_terminate(void);

/**
  * \fn BOOL fx_close_network()
  * \brief shutdown the connect to fetion's servers.
  *
  * this function will close the fetion's socket from fetion's servers, if you will not use fetion anymore
  * \return TRUE if init successfully, otherwise return FALSE.
*/
FX_EXPORT BOOL fx_close_network();

/** @} end of init_libfetion */



/**
 * \addtogroup fetion_login  
 * @{
 */

/**
 * \addtogroup  simple_fetion_login  
 * @{
 */

/**
  * \fn BOOL fs_login(const char *uid, const char *password)
  * \brief login fetion.
  *
  * This function contain all the fetion login operates. 
  * and without callback function, when it return show login is finished.  
  * this function implement login,  get contact list and get presence operates.
  *
  * \param uid The login info of the usr fetion uid or mobile_no .
  * \param password The login info of the usr password.
  *
  * \return TRUE if login successfully, otherwise return FALSE.fx_get_error();...
  *
  * \sa fx_login
  */
FX_EXPORT BOOL fs_login(const char *uid, const char *password);



/** @} end of  simple_fetion_login */


/**
 * \addtogroup  generic_fetion_login_functions  
 * @{
 */

/**
  * \fn void fx_set_login_status(int longin_status)
  * \brief set the user login status.
  *
  * This function will set the user login status. 
  *
  * \param login_status The login status of you want to set.
  *
  * \sa fs_login
  */
FX_EXPORT void fx_set_login_status(int longin_status);

/**
  * \fn void fx_login(const char *uid, const char *password, EventListener func, void *args)
  * \brief login fetion.
  *
  * This function contain all the fetion login operates. 
  * and without callback function, when it return show login is finished.  
  * this function implement login,  get contact list and get presence operates.
  *
  * \param uid The login info of the usr id or mobile_no.
  * \param password The login info of the usr password.
  * \param status_login The place which store the error info.
  *
  * \sa EventListener 
  *
  *
  * \sa fs_login
  */
FX_EXPORT int fx_login(const char *uid, const char *password, EventListener func, void *args);

/**
 * \fn void fx_relogin()
 * \brief relogin fetion when fetion have break from server..
  *
*/
FX_EXPORT int fx_relogin(EventListener func, void *args);

/**
  * \fn void fx_loginout()
  * \brief loginout fetion.
  *
  * This function will done all loginout fetion operates, when you want to loginout fetion. 
  *
  * \sa fx_login
*/
FX_EXPORT void fx_loginout();

#if 0
/**
  * \fn int fs_keep_alive()
  * \brief send a keep alive package. 
  *
  * This function will send a keep alive package to fetion server to keep alive int the expires time.
  * ****this function will be removed in later version****, because it can done by libfetion.
  *
  * \sa fetion_data_get_expirestime
  *
  * \return non zero on successfully, otherwise return zero.
*/
FX_EXPORT int fs_keep_alive();
#endif
/** @} end of generic_fetion_login_functions */

/** @} end of fetion_login */

/**
 * \addtogroup  system_msg_cb  
 * @{
 */

/**
  * \fn void fx_set_system_msg_cb(EventListener func, void* args)
  * \brief set the system message callback funtion. 
  *
  * This function will set the fuction address which is be sended  all fetion system messages to usr.
  * like ....
  *
  * \sa ...
*/
FX_EXPORT void fx_set_system_msg_cb(EventListener func, void* args);

/** @} end of system_msg_cb */

/**
* \addtogroup fetion_receive  
* @{
*/

/**
  * \fn Fetion_MSG *fx_get_msg(long uid)
  * \brief get the uid 's message. 
  *
  * \param uid The message 's sender. 
  *
  * you should usr the fx_destroy_msg function to destroy the msg which you get
  *
  * \return NULL if the uid no send message, or Fetion_MSG a struct which store message info.
  *
  *
  * \sa FX_NEW_MESSAGE fx_destroy_msg
*/
FX_EXPORT Fetion_MSG *fx_get_msg(long uid);

/**
  * \fn void fx_destory_msg(Fetion_MSG *msg)
  * \brief destroy the fetion message, it will free msg's memory, and set msg = NULL. 
  *
  * \param msg The  fetion message will be destroy. 
  *
  *
  * \sa fx_get_msg
*/
FX_EXPORT void fx_destroy_msg(Fetion_MSG *msg);

/** @} end of fetion_receive */

/**
 * \addtogroup fetion_send_sms  
 * @{
 */

/**
 * \addtogroup simple_send_sms_functions  
 * @{
 */

/**
  * \fn BOOL fs_send_sms(long who, const char *message)
  * \brief simple send smsfunctions
  *
  * \param who The user uid  of you want to send.
  * \param message The content of you want to send.
  *
  * \return TRUE if init successfully, otherwise return FALSE..
  *
  * \sa fx_send_sms
*/
FX_EXPORT BOOL fs_send_sms(const long who, const char *message);


/**
  * \fn BOOL BOOL fs_send_sms_by_mobile_no(const char *mobile_no, const char *message)
  * \brief simple send smsfunctions
  *
  * \param mobile_no The mobile number of you want to send.
  * \param message The content which you want to send.
  *
  * \return TRUE if init successfully, otherwise return FALSE..
  *
  * \sa fx_send_sms_by_mobile_no
*/
FX_EXPORT BOOL fs_send_sms_by_mobile_no(const char *mobile_no, const char *message);


/**
  * \fn BOOL fs_send_sms_to_self(const char *message)
  * \brief send a shortmessage to user self 
  *
  * \param message The content which you want to send.
  *
  * \return TRUE if init successfully, otherwise return FALSE..
  *
  * \sa fx_send_sms_to_self
*/
FX_EXPORT BOOL fs_send_sms_to_self(const char *message);

/** @} end of simple_send_sms_functions */

/**
 * \addtogroup generic_send_sms_functions  
 * @{
 */

/**
  * \fn int fx_send_sms(const long who, const char *message, EventListener func,void *args)
  * \brief send sms. 
  *
  * \param who The user uid  which you want to send.
  *
  * \param message The content which you want to send.
  *
  * \param func The send sms operate's callback function's address, and the operate result will pass to this function.
  * \sa EventListener
  *
  * \param args The send_sms operate's callback function's args. 
  *
  * \return 0 if send sms fail immediately, or can get the result from to callback_send_sms func.
  *
  *
  * \sa fs_send_sms
*/
FX_EXPORT int fx_send_sms(const long who, const char *message, EventListener func,void *args);


/**
  * \fn int fx_send_sms_to_self(const char *message, EventListener func,void *args)
  * \brief send sms to self.
  *
  * \param message The content which you want to send.
  *
  * \param func The send sms operate's callback function's address, and the operate result will pass to this function.
  * \sa EventListener
  *
  * \param args The send_sms operate's callback function's args. 
  * 
  * \return 0 if send sms fail immediately, or can get the result from to callback_send_sms func.
  *
  *
  * \sa fs_send_sms_to_self
*/
FX_EXPORT int fx_send_sms_to_self(const char *message, EventListener func,void *args);


/**
  * \fn int fx_send_sms_by_mobile_no(const char *mobile_no, const char *message, EventListener func, void *args)
  * \brief send sms by mobile numbers. 
  *
  * \param mobile_no The mobile number which you want to send.
  * \param message The content which you want to send.
  *
  * \param func The send sms operate's callback function's address, and the operate result will pass to this function.
  * \sa EventListener
  *
  * \param args The send_sms operate's callback function's args. 
  *
  * \return 0 if send sms fail immediately, or can get the result from to callback_send_sms func.
  *
  *
  * \sa fs_send_sms_by_mobile_no
*/
FX_EXPORT int fx_send_sms_by_mobile_no(const char *mobile_no, const char *message, EventListener func, void *args);

/**
  * \fn void fx_set_longsms(BOOL bl)
  * \brief set the send sms mode, it maybe longsms or sms normally. 
  *
  *  longsms mode: it will send 180 characters in one short message,
  *  sms normally mode: it will send 70 characters in one short message,
  *
  * \param bl The TRUE is set longsms mode, FALSE set normally mode .
*/
FX_EXPORT void fx_set_longsms(BOOL bl);

/** @} end of generic_send_sms_functions */

/** @} end of fetion_send_sms */