gloox 之 MessageSession

MessageSession类对象是任意两个实体之间消息会话的抽象。

详细说明：
MessageSession是原始态和老式消息会话形式的一种替代。
原始的接口，它使用简单MessageHandler类的派生类，是基于一种全有或全无的方法。
一旦用ClientBase对象注册此原始接口，则此MessageHandler的派生类会收到发给此ClientBase对象所有的消息节（message stanza），并且不得不自己对消息节进行过虑。
MessageSession向聊天会话中增加了一种抽象。一个MessageSession对象只对一个全JID负责。
此MessageSession对象可以被称作消息过虑器（messageFilters）扩展，以提供另外的功能，

比如：消息事件（MessageEvents）， 聊天状态通知（ChatState），或带内字节数据流。

你可以依然使用老式的MessageHandler类，

但是消息不会一起传递到MessageHandler和为那个JID创建的一个MessageSession对象中，
即消息只会递进其中之一，MessageSession具有较高的优先级，消息被传递其中，

而MessageHandler则不会传进消息。

使用MessageSession比使用老式的MessageHandler有如下优点：
1、MessageSession对象自动创建。
2、以JID过虑
3、消息跟踪(thread id)的自动处理
4、简单的消息发送
5、支持消息过虑器（MessageFilters）
用法：
从MessageSessionHandler派生一个对象，重写handleMessageSession()函数在某种结构中存储新的会话，或创建一个新的聊天窗口，或其它。

然后用ClientBase对象的registerMessageSessionHandler()函数注册此对象。例：

void MyClass::myFunc()
 {
   JID jid( "[e-mail]/gloox" );
   j = new Client( jid, "password" );          //以前说过，Client继承自ClientBase类
   [...]
   j->registerMessageSessionHandler( this, 0 );
 }

 

此时 MyClasss 就是一个MessageSessionHandler。
例子中，MyClass也需要MessageHandler,MessageEventHandler和ChatStateHandler。
以上三种处理器被MessageSession对象注册用来处理各自的事件

 

virtual void MyClass::handleMessageSession( MessageSession *session )
 {
   // for this example only, we delete any earlier session
   if( m_session )
     j->disposeMessageSession( m_session );
   m_session = session;
   m_session->registerMessageHandler( this );

   // the following is optional
   m_messageEventFilter = new MessageEventFilter( m_session );
   m_messageEventFilter->registerMessageEventHandler( this );
   m_chatStateFilter = new ChatStateFilter( m_session );
   m_chatStateFilter->registerChatStateHandler( this );
 }

当消息事件（Message Events）和聊天状态(Chat States)到达时，
MessageEventHandler::handleMessageEvent()和chatStateHandler::handleChatState()就会分别被调用。

 virtual void MyClass::handleMessageEvent( const JID& from, MessageEventType event )
 {
   // display contact's Message Event
 }

 virtual void MyClass::handleChatState( const JID& from, ChatStateType state )
 {
   // display contact's Chat State
 }

 

想要让好友知道自己正在输入信息或己经关闭聊天窗口，

则需要分别调用raiseMessageEvent()和setChatState()函数即可，例如：

// user is typing a message
 m_messageEventFilter->raiseMessageEvent( MessageEventComposing );

 

 // acknowledge receiving of a message
 m_messageEventFilter->raiseMessageEvent( MessageEventDelivered );

 

 // user is not actively paying attention to the chat
 m_chatStateFilter->setChatState( ChatStateInactive );

 

 // user has closed the chat window
 m_chatStateFilter->setChatState( ChatStateGone );

 

向一个MessageSession代表的一个好友聊天会话发送消息，

使用send(const std::string& message,const std::string& subject)函数。
你不必关心消息头，消息追踪（thread id）,这些都是自动添加的。

m_session->send( "Hello World!", "No Subject" );

 

初始化一个聊天会话(chat session),你所做的所有工作就是创建一个MessageSession对象,

并且用它注册一个MessageHandler对象:
MessageSession* MyClass::newSession( const JID& to )
{
   MessageSession *session = new MessageSession( m_client, to );
   session->registerMessageHandler( this );
   return session;
}

关于带内字节流(In-Band Bytestreams)的实现方法,参考InBandBytestreamManager类.
 
注意:你永远不要手工删除一个MessageSession对象,

而是调用ClientBase::disposeMessageSession()来完成这个工作.
 

MessageSession(  ClientBase*     parent,
                            const JID&      jid,
                            bool                wantUpgrade = true;
                            int                   types = 0
)
为给定的JID创建一个MessageSession对象.建议提供一个全JID,也即是,它需要设置一个资源.
如果没有设定资源将导致一个异常.一个消息跟踪(thread id)将被创建并且在整个会话过程中都会与每一个消息一起发送.
参数:
parent    进行通信的ClientBase对象
jid       远程联系人的全Jid。如果你不知道对方的全Jid（大概是普遍情况），

           但又想用MessageSession回应此联系人，那么把wantUpgrade参数
          设为true(或不更改它，即默认true)
wantUpgrade  标示gloox是否尽量匹配发到此MessageSession的一个全JID发来的消息。

                     如果不确定，请使用默认值。
             MesssageSession对象直接与服务器通信或一个没有资源的组件JID，

            这可能是唯一不使用默认值的场合。
             这样的“提升（upgrade）”只发生一次 。
types     这个MessageSession对象应该接收的子节类型（StanzaSubType）列表的值。

             只有StanzaMessage* 类型有效。
            默认值0，指所有类型都被接收。

 

 

void disposeMessageFilter(MessageFilter *mf)
 从MessageSession对象中删除一个MessageFilter（消息过滤器）。
  （译注：ChatStateFilter, InBandBytestream,  MessageEventFilter 都继承自MessageFilter）
参数：
    mf   要移除和释放的 MessageFilter对象
注：如果只是移除（不释放）MessageFilter对象，则使用removeMessageFilter()函数。

 

void  registerMessageFilter(MessageFilter* mf)
使用此函数向MessageSession对象中注册一个新的MessageFilter对象。此过滤器有能力读取和（/或）修改一个消息节的内容。
注意：
    此MessageSession对象将成为此过滤器的宿主，过滤器对象被MessageSession的析构函数删除。
    如果在MessageSession销毁之前，之前摆脱此过滤器，则调用disposeMessageFilter()。

void removeMessageFilter(MessageFilter * mf)
从MessageSession中移除一个MessageFilter对象。

 

void  registerMessageHandler(MessageHandler* mh)
此函数使MessageSession和一个MessageHandler对象联合起来。此MessageHandler将要收到此MessageSession远程联系人发来的所有消息。

 

void removeMessageHandler()
此函数将清除内部指针指向的MesssageHandler对象。并且使消息的递送无效。

 

void resetResource()
此函数重置会话的目标JID，重置成随后发送消息发往的那个JID。服务器确定要递送的最好资源（the server will determine the best resource to deliver to）。当目标资源改变出席时（如，离开

或下线）有用。（原句：This function resets the session's target JID to its bare form such that subsequently sent messages will be sent to that bare JID. The server will

determine the best resource to deliver to. Useful if the target resource changed presence to e.g. away or offline.）

 

void send( const std::string & message,
           const std::string & subject=""
)
快速地发送一条消息（可选择地，下属内容（subject）），比较方便。这是从MessageSession发送消息的首选方法。
参数：
message 将要发送的消息串
subject 可选择的，将要发送的下属内容

 

void setThreadID( const std::string & thread)
设定一个消息跟踪的ID值，例如，如果继续一个特殊的消息跟踪。不必手动地设置消息跟踪ID值。

const std::string& threadID()const
默认情况下，一个消息跟踪ID和每条消息一起发送。
返回此会话对象的消息跟踪ID值。

 

const JID& targer()const
返回此会话远客联系人的JID

 

int types()const
返回此MessageSession对象（即会话对象）要接收的消息类型列表。只对StanzaMessage* 类型有效。