gloox 之 ClientBase

gloox 之 ClientBase

是Client类和Component类的公共基类
它继承了TagHandler,ConnectionDataHandler,CompressionDataHandler,TLSHandler这四类。

此类管理连接的建立，认证，注册过虑器和调用

构造和析构函数：
ClientBase(  const std::string & ns,
                   const std::string & server,
                   int                        port = -1
)
构造一个ClientBase对象，你不必直接使用此类，而是使用Client 或 Component 代替
参数：
        ns         合适的流命名空间，不是jabber:client ，就是jabber:component
        server    连接到的服务器
        port       连接到服务器的端口，默认值-1，经由服务位置（DNS SRV）查找到端口或使用XMPP核心协议定义的默认端口5222

ClientBase (  const std::string  & ns,
                    const std::string  & password,
                    const std::string  & server,
                    int                          port = -1
)
构造一个ClientBase对象，你不必直接使用此类，而是使用Client 或 Component 代替
参数：
       ns         合适的流命名空间，不是jabber:client ，就是jabber:component
       password  进一步验证的密码
       server    连接到的服务器
       port       连接到服务器的端口，默认值-1，经由服务位置（DNS SRV）查找到端口或使用XMPP核心协议定义的默认端口5222

成员函数：

bool    authed() const
确定是否发生认证和认证成功。
返回值： true  认证己经发生，并且认证通过； 否则false 

AuthenticationError  authError() const
当你从ConnectionListener收到一个类型ConnAuthenticationFailed的连接错误（ConnectionError）时，可以使用此函数接收认证错误的类型。（译注  此错误类型是 枚举类型，）
返回值：认证的类型，否则为AuthErrorUndefined

bool  compression () const
返回 当前流（Stream）的压缩效果是否有效（非必须）

CompressionBase* compressionImpl() const
此函数返回当前正在使用的压缩具体实现。

bool connect(bool block = true)         
初始化一个到服务器的连接。当连接建立起来后，此函数会一直阻塞。你可以用一个阻塞状态的连接或你可以让它连接建立后立即返回。如果是后者，你必须担付起调用recv()函数接收数据并把数据传给解析器的责任。
参数：
      block   true为阻塞（默认）；false非阻塞。
返回值：
     false,服务器没有设置或拒绝连接；否则true
注意： 从0.9版开始，添加了一个附助函数，onDisconnect(),当连接返回false时，此函数被调用。

ConnectionBase* connectionImpl() const
此函数返回一个当前正在使用的具体的连接实现

virtual  Disco* disco() const
此函数给出了一个得到Disco对象的接口。（译注：Disco 实现了服务发现功能）

void  disposeMessageSession( MessageSession* session )
从MessageSession列表中移除并释放一个指定的 MessageSession

TLSBase* encryptionImpl() const
此函数返回当前正在使用的具体加密实现

const std::string getID()
创建一个当前实列中唯一的字符序列，作为查询的ID值（query节)
返回值：查询节使用的唯一ID值

StatisticsStruct   getStatistics()
返回一个StatisticsStruct结构，此结构统计当前活动连接的字节数和节数（stanza counts）

void handleCompressedData( const std::string & data )  （虚函数）
当压缩完毕时，此函数被调用
参数：
     data   压缩后的数据
    须实现  CompressionDataHandler 接口

void handleConnect( const ConnectionBase* connection ) (虚函数)
当原始TCP连接建立起来后，此函数被调用
须实现 ConnectionDataHandler接口

void handleDecompressedData( const std::string & data ) (虚函数)
解压缩完毕时，此函数被调用
须实现CompressionDataHandler接口

void handleDecryptedData( const TLSBase*  base ,
                                         const std::string  & data
)  (虚函数)
重新实现此函数从TLSBase实例接收解密过的数据
参数:
      base   函数调用的加密实现
      data    解密过的数据(比如,准备解析)
须实现TLSHandler接口

void handleDisconnect( const ConnectionBase* connection,
                                   ConnectionError             reason )    (虚函数)
当一个原始的TCP连接断开时,此函数被调用
参数:  connection   一个连接
          reason        断开的原因
须实现ConnectionDataHandler接口


void handleEncryptedData ( const TLSBase*  base,
                                          const std::string & data ) (虚函数)
实现此函数从一个TLSBase实例接收加密过的数据
参数: 
       base    此函数需要的一个加密实现
       data     加密后的数据(比如,将要在线路发送的数据)
 须实现 TLSHandler


void  handleHandshakeResult(   const TLSBase*  base,
                                                bool                   success,
                                                CertInfo &           certinfo
) (虚函数)
实现此函数接收一个TLS握手的结果
参数:
      base    此函数需要的加密实现
      success  握手是否成功
      certinfo    服务器的认证信息
须实现TLSHandler接口


void   handleReceivedData( const ConnectionBase*  connection,
                                         const  std::string & data ) (虚函数)
此函数处理从层传输接收数据
参数:
      connection   接收数据的那个连接
      data             接收到的数据
须实现ConnectionDataHandler


void handleTag ( Tag* tag ) (虚函数)
当一个己被注册过的XML元素到达时此函数被调用。与gloox中的众多处理器（handlers）一样，在此函数返回后，tag数据将被释放（deleted），如果此后你需要一个复本，调用Tag::clone()函数来创建。
参数：  tag   完整的标签
须实现 TagHandler

const JID& jid()
返回当前JID,如果使用setAuthzid()设置了一个认证ID，则返回此认证ID
注意：如果你更改了JID的服务器部分，处于连接中的服务器不会与你同步，你不得不自己调用setServer()设置。

LogSink& logInstance()
返回ClientBase对象及其所有相关对象的LogSink实例
返回值：当前ClientBase对象使用的LogSink实例

virtual  const std::string& password()const
返回当前连接使用的密码


int port()const
返回连接的端口，-1即经由查找服务记录得到的，或者XMPP定义的5222

ConnectionError   recv(int timeout = -1)
调用它，从套接字上循环接收数据并且传给解析器。唯一用到的地方就是使用了非阻塞连接。
参数：
      timeout  超时毫秒数。-1即一直阻塞，只到收到一些数据。
返回值： 连接的状态


void  registerConnectionListener( ConnectionListener* cl )
把ConnectionListener对象注册进去，用来接收连接通告


void registerIqHandler( IqHandler* ih,
                                  const std::string& xmlns)
把IqHandler注册进去为xmlns名空间接收Iq节通告。一个名空间只有一个处理器（handler）是有可能的。
参数： ih    接收Iq节通知的对象
           xmlns  上述对象处理的名空间


void registerMessageHandler( MessageHandler * mh)
把MessageHandler对象注册进去，用来接收消息节（Message stanza）通告


void registerMessageSession( MessageSession* session )
注册一个指定的MessageSession对象，此对象用来接收从会话（一个MessageSession代表一个会话）目标JID发来的消息。
注意 ：ClientBase对象会成为MessageSession对象的宿主，当ClientBase对象的析构函数被调用时，MessageSession对象跟着消亡。如果你想在ClientBase对象消亡之前避免MessageSession对象被释放，就要利用disposeMessageSession()函数。
因为一个MessageSession对象会自动注册自己，所以不必直接调用此函数。

void registerMessageSessionHandler( MessageSessionHandler* msh,
                                                         int                                    types  =0 )
利用此函数，你可以在Client对象中注册一个MessageSessionHandler对象，
（可选择地）MessageSessionHandler可以只收到消息会话（MessageSessions）中给定的消息类型。也可以成为每一种消息类型的唯一处理器。
如果没有为远程JID注册一个MessageHandler对象，那么当每一个消息节到达时，就会为那个JID创建一个MessageSession对象。
参数： msh     接收最新创建的MessageSession对象的那个对象
           types  处理器将要收到的消息类型描述。只有StanzaMessage* 类型是有效的，取0值即所有类型。


void registerMUCInvitationHandler( MUCInvitationHandler * mih )
向ClientBase注册一个 MUCInvitationHandler处理器


void registerPresenceHandler( const JID& jid, PresenceHandler* ph)
为指定的JID注册一个新的PresenceHandler（出席处理器）。此JID的出席消息不会再传递到共同的 PresenceHandler中了。这个功能最初的想法是为了MUC实现考虑的。


void registerPresenceHandler( PresenceHandler* ph)
把PresenceHandler对象注册进去，用来接收出席消息节。

void  registerStatistcsHandler( StatisticsHandler* sh)
把StatisticsHandler对象注册进去，用来统计最近连接上的每个时间段的消息节的收和发。
你也可以手动调用getStatistics()函数。每一个ClientBase对象同一时间只有一个StatisticsHandler是有可能的。


registerSubscriptionHandler( SubscriptionHandler* sh )
把SubscriptionHandler对象注册进去,接收订阅节通告


void registerTagHandler( TagHandler*  th,
                                     const std::string & tag,
                                     const std::string & xmlns )
把TagHandler对象注册进去,接收符合指定名空间内给定的根标签的数据包

void removeConnectionListener( ConnectionListener * cl )
从连接监听列表中移除一个监听对象


void removeIDHandler( IqHandler* ih)
从未决操作的处理器列表中移除一个指定的IqHandler对象,别外使用trackID()函数。必需的，举例，在关闭一个GUI元素时，发生了未决操作。

void removeIqHandler( const std::string & xmlns )
从Iq处理器列表中移除一个指定名空间的处理器


void removeMessageHandler( MessageHandler * mh )
从消息处理器列表中除除指定的对象

void removeMUCInvitationHandler()
移除当前注册的MUCInvitationHandler对象


void removePresenceHandler( const JID&  jid, PresenceHandler * ph )
为一个指定的 JID 从出席处理器列表中移除一个指定的处理器对象
参数：
    jid     移除那个JID的出席处理对象（可能多个）
    ph     从列表中移除的PresenceHandler对象，如果取0值，指定JID的所有出席处理器都会被移除


void  removePresenceHandler( PresenceHandler* ph )
移除一个指定的出席处理器对象


void removeStatisticsHandler()
移除当前的StatisticsHandler对象


 void removeSubscriptionHandler( SubscriptionHandler* sh )
从订阅处理器列表中移除一个指定的处理器


 void removeTagHandler ( TagHandler*  th,
                                      const std::string & tag,
                                     const std::string & xmlns )
从标签处理器列表中移除一个符合指定元素和名空间的处理器对象


bool  sasl() const
返回SASL当前是否有效（不是必需调用的）


void  send( Tag* tag )(虚函数)
在己建立的连接上发送指定的标签。ClientBase对象成为此Tag对象的宿主，发送之后会删除它。
你不应该在此Tag被发送之后还使用它，如果你确实想使用，请调用Tag::clone进行深度复制。

const std::string& server()const
返回当前连接到的服务器


void setAuthzid( const JID & zuthzid )
设定一个认证ID（authzid）,如果服务支持此ID并且此ID有足够的权限，可能发生这样的情况，以[email protected] 认证，却像[email protected] 的行为。

void setCACerts( const StringList& cacerts)
向ClientBase 设置一些可信赖用于验证一个服务器证书的根证书
参数：  cacerts   保存增强保密格式的根证书文件一个绝对路径列表


void setClientCert( const std::string & clientKey,
                           const std::string & clientCerts )
使用此函数设定用户的证书和密钥。证书将在服务发出需要时被提供和用于SASL 外部证书（SASL EXTERNAL）。用户的所有证书应该是捆在一起保存在增强保密文件格式中。第一个证书应该是用户的证书，接下来的每个证书应该标记为更以前的。
注意： 这些证书不需要和那些用于认证服务器的证书一样。


void setCompression( bool compression )
用于变换流的压缩开关。默认：开，如果可以的话。流压缩唯一不需要时就是用它会产生错误，否则，就要保持 开的状态。


void setCompressionImpl( CompressionBase * cb )
如果你有其它的压缩算法类，用此函数设置进去。这样你的类会在connect()之前被调用。如果己经设定了一个压缩实现，则以前的会被删除。


void setConnectionImpl( ConnectionBase* cb)
如果你有其它的实现 UDP，SCTP（诸如此类）连接的实现类，用此函数设定进去，这样你的类会在connect()之前被调用。如果己经设定了这样的一个实现类，那么以前的会被删除。


void setEncryptionImpl( TLSBase * tb )
如果你有其它的支持硬加密的类，用此函数设置进去。这样你的类会在connect()之前被调用。如果己经设定了一个加密实现，则之前的会被删除。


void setPassword( const std::string & password )
设置连接到XMPP服务器用到的密码。

void setPort( int port )
设置连接到的服务器端口。如果 要么使用默认值5222或服务记录中存在，那么它就不是必须的。

void setSasl（bool  sasl ）
 切换SASL的开关，默认：on, 唯一关闭的可能是 使用它有了问题


void setSASLMechanisms( int mechanisms )
此函数限制gloox 使用的SASL机制。默认情况下，支持gloox允许的所有机制。如果舍弃一个机制（或多个），则从SaslMechAll变量中像这样移除：
   int  mymechs = SaslMechAll ^ SaslMechDigestMd5;


void setServer ( const std::string & server )
设定要连接到的XMPP服务器
参数：   server  不是IP就是一个完全合格的域名称
注意：如果你改变了服务器，JID的服务器部分不会自动同步。你必须手动调用 jid()和JID::setServer()。
          这个函数对使用中的Connection(Base) 服务器进行同样的设定。


void setTls( TLSPolicy tls )
设置TLS策略。默认情况下：如果允许，TLS是有效的。TLS唯一无效的情况就是在使用它时产生了错误。


GLOOX_DEPRECATED   void setTls( bool tls )
切换使用TLS的开关(如果允许)。默认：开（如果允许）。TLS唯一无效的情况就是在使用它时产生了错误。


void setXmlLang( const std::string & xmllang )
在初始化流时，设置xml:lang属性的值。
参数：
     xmllang  流的语言识别码。必须符合2.12节XML的定义和RFC3066。默认是‘en’（英语）


ConnectionState  state( )const
返回当前连接的状态


StreamError  streamError() const

 此函数用来检索出流错误，（此后可以做进一步挽救）并且从ConnectionListener接收到类型为ConnStreamError 的连接错误。

注意：
此函数的返回值只有在ConnectionListener::onDisconnect()中使用才有意义。


const Tag* streamErrorAppCondition()const
此函数用来检索一个流错误中应用特有的错误情形
返回值：
返回一个流错误中应用特有的错误元素。当没有错误发生或没有找到对应的错误元素时，返回0


const std::string & streamErrorCData()const
 此函数检索一个流错误中定义的包含XML字符数据的元素。RFC3920只定义了一种有可能的情形（查看其它主机）
返回值：
流中错误元素的文本（只对查看其它主机）


const std::string streamErrorText( const std::string & lang="default" )const
如果可能，返回指定语言的一个流错误文本信息。如果要求的语言无效，那么返回默认的文本信息（xml:lang 属性除外）

参数：
lang   希望的语言标识符。它必须符合XML规格说明书中的2.12节和RFC3066。如果为空，则返回默认文本。
返回值：
   一个流错误的文术描述。如果没有流错误发生，则返回空

bool  tls( ) const
返回TLS是否在当前有效。（不必使用）
返回值：  当前TLS 状态


void trackID(  IqHandler*             ih,
                    const std::string& id,
                    int                        context
)
调用此函数，当指定id属性值IQ节到达时，应用将得到通知。因为ID都是唯一的，所以通知只有一次

参数：
     ih             此IqHandler将收到通知
     id             跟踪的ID
     context     恢复上下文准许的值

virtual const std::string& username()const
重新实现此函数向一个连接意图提供一个名称


void  whitespacePing()
向服务器发送一个空白的ping命令


 const std::string& smlLang()const
检索初始化流中xml:lang属性的值，如果没有使用setXmlLang()改变它的值，就是默认值'en'

void xmppPing(  const JID& to )
以指定的JID发送一个XMPP ping命令（XEP-0199）。没有方法知道远程实例是否回应此ping命令（除非为urn:xmpp:ping名空间注册一个IQ处理器）