关于xmpp协议的注册模块的实现原理（gloox库）

这里涉及到几个类：

一.RegistrationHandler：

1.简要说明：虚拟接口，接收来自Registration实体的事件信息（A virtual interface that receives events from an Registration object.）

继承该接口的类可以被Registration实体注册一个RegistrationHandlers子类，Registration实体触发的行为所返回的结果可以转发到这个字类。

（Derived classes can be registered as RegistrationHandlers with an Registration object. Incoming results for operations initiated through the Registration object are forwarded to this handler.）

2.这个类里面定义了一些消息类型：

  enum RegistrationResult
  {
    RegistrationSuccess = 0,          /**申请帐户，账户删除，密码修改成功< The last operation (account registration, account
                                                 * deletion or password change) was successful. */
    RegistrationNotAcceptable,       /**< 406: 没有提供所有必须的信息Not all necessary information provided */
    RegistrationConflict,                 /**< 409: 用户名已经存在Username alreday exists. */
    RegistrationNotAuthorized,       /**< 删除用户：没有授权的实体等待授权时间过长Account removal: Unregistered entity waits too long
                                                 * before authentication or performs tasks other than
                                                 * authentication after registration.<br>
                                                 * 密码修改：服务器认为通道的安全程度不足以保证密码的修改

                                                 * Password change: The server or service  does not consider
                                                 * the channel safe enough to enable a password change. */
    RegistrationBadRequest,            /**帐户移除：

                                                 *< Account removal: The &lt;remove/&gt; element was not
                                                 * the only child element of the &lt;query/&gt; element.
                                                 * Should not happen when only gloox functions are being
                                                 * used.<br>

                                                 *密码修改：不包含完整的密码修改要求的信息
                                                 * Password change: The password change request does not
                                                 * contain complete information (both &lt;username/&gt; and
                                                 * &lt;password/&gt; are required). */
    RegistrationForbidden,             /**< Account removal: The sender does not have sufficient
                                                 * permissions to cancel the registration. */
    RegistrationRequired,               /**< Account removal: The entity sending the remove
                                                 * request was not previously registered. */
    RegistrationUnexpectedRequest,     /**< Account removal: The host is an instant messaging
                                                      * server and the IQ get does not contain a 'from'
                                                       * address because the entity is not registered with
                                                       * the server.<br>
                                                       * Password change: The host is an instant messaging
                                                       * server and the IQ set does not contain a 'from'
                                                       * address because the entity is not registered with
                                                       * the server. */
    RegistrationNotAllowed,                 /**< Password change: The server or service does not allow
                                                       * password changes. */
    RegistrationUnknownError             /**< An unknown error condition occured. */
  };

 

3.RegistrationHandler类定义的接口：

class GLOOX_API RegistrationHandler
  {
    public:
           virtual ~RegistrationHandler() {}

      /**

       *重新实现这个函数去接收Registration::fetchRegistrationFields() 返回的结果
       * Reimplement this function to receive results of the
       * @ref Registration::fetchRegistrationFields() function.

       * @param from 服务器
       * @param from The server or service the registration fields came from.

       * @param fields  注册字段或运算结果（服务器要求的注册字段的或运算结果）
       * @param fields The OR'ed fields the server requires. From @ref Registration::fieldEnum.

       * @param instructions 服务器发送的附加信息
       * @param instructions Any additional information the server sends along.
       */
       virtual void handleRegistrationFields( const JID& from, int fields,
                                             std::string instructions ) = 0;

      /**

       * 调用 handleAlreadyRegistered 这个函数可以让我们知道Registration::createAccount()被已经认证的流上被调用

       * This function is called if @ref Registration::createAccount() was called on an authenticated
       * stream and the server lets us know about this.
       */
       virtual void handleAlreadyRegistered( const JID& from ) = 0;

      /**

       *调用这个函数以通知Registration实体的行为所引起的结果
       * This funtion is called to notify about the result of an operation.
       * @param from The server or service the result came from.
       * @param regResult The result of the last operation.
       */
       virtual void handleRegistrationResult( const JID& from, RegistrationResult regResult ) = 0;

      /**

       * 这个函数会被调用如果服务器提供的数据表格连同传统的注册字段

       * This function is called additionally to @ref handleRegistrationFields() if the server
       * supplied a data form together with legacy registration fields.
       * @param from The server or service the data form came from.
       * @param form The DataForm containing registration information.
       */
       virtual void handleDataForm( const JID& from, const DataForm& form ) = 0;

      /**

       *如果服务器不提供注册但是向用户指向一个外部的url

       * This function is called if the server does not offer in-band registration
       * but wants to refer the user to an external URL.
       * @param from The server or service the referal came from.
       * @param oob The OOB object describing the external URL.
       */
      virtual void handleOOB( const JID& from, const OOB& oob ) = 0;

  };

 

 

 

二.IqHandler类

1.简要说明:一个虚拟接口，可以重新实现用来接收IQ节，继承该接口的类可以被Client 类注册为IqHandlers ，当返回一个IQ包的时候handleIq() 会 被调用。（A virtual interface which can be reimplemented to receive IQ stanzas. Derived classes can be registered as IqHandlers with the Client.Upon an incoming IQ packet @ref handleIq() will be called.）

 

2.类的实现：

class GLOOX_API IqHandler
  {
    public:
           virtual ~IqHandler() {}

      /**
       * Reimplement this function if you want to be notified about incoming IQs.
       * @param iq The complete IQ stanza.
       * @return Indicates whether a request of type 'get' or 'set' has been handled. This includes
       * the obligatory 'result' answer. If you return @b false, a 'error' will be sent.
       * @since 1.0
       */
       virtual bool handleIq( const IQ& iq ) = 0;

      /**

       * 处理一些特殊的IQ节（要在 ClientBase::trackID()注册)
       * Reimplement this function if you want to be notified about
       * incoming IQs with a specific value of the  id attribute. You
       * have to enable tracking of those IDs using Client::trackID().
       * This is usually useful for IDs that generate a positive reply, i.e.
       *  iq type='result'  id='reg'; where a namespace filter wouldn't
       * work.
       * @param iq The complete IQ stanza.
       * @param context A value to restore context, stored with ClientBase::trackID().
       * @note Only IQ stanzas of type 'result' or 'error' can arrive here.
       * @since 1.0
       */
      virtual void handleIqID( const IQ& iq, int context ) = 0;

  };

 

三.Registration类

1.简要说明：用户注册类，向服务器请求要求的注册字段，处理发送注册信息。

2.类的内部包含一个Query类，该类继承与于可扩展节类StanzaExtension，Query类的作用是生成一个注册节（用户注册，用户删除）。

 class GLOOX_API Registration : public IqHandler
{
    public:

           class Query : public StanzaExtension
          {
          public:
          /**
           * Creates a new object that can be used to carry out a registration.
           * @param form A DataForm containing the registration terms.
           */
          Query( DataForm* form );

          /**
           * Creates a new object that can be used to carry out a registration.
           * @param del Whether or not to remove the account.
           */
          Query( bool del = false );

          /**
           * Creates a new object that can be used to carry out a registration.
           * @param fields Bit-wise ORed fieldEnum values describing the valid (i.e., set)
           * fields in the @b values parameter.
           * @param values Contains the registration fields.
           */
          Query( int fields, const RegistrationFields& values );

          /**
           * Creates a new object from the given Tag.
           * @param tag The Tag to parse.
           */
          Query( const Tag* tag );

          /**
           * Virtual Destructor.
           */
          virtual ~Query();

          /**
           * Returns the contained registration form, if any.
           * @return The registration form. May be 0.
           */
          const DataForm* form() const { return m_form; }

          /**
           * Returns the registration instructions, if given
           * @return The registration instructions.
           */
          const std::string& instructions() const { return m_instructions; }

          /**
           * Returns the registration fields, if set.
           * @return The registration fields.
           */
          int fields() const { return m_fields; }

          /**
           *
           */
          const RegistrationFields& values() const { return m_values; }

          /**
           * Indicates whether the account is already registered.
           * @return @b True if the &lt;registered&gt; element is present, @b false otherwise.
           */
          bool registered() const { return m_reg; }

          /**
           * Indicates whether the account shall be removed.
           * @return @b True if the &lt;remove&gt; element is present, @b false otherwise.
           */
          bool remove() const { return m_del; }

          /**
           * Returns an optional OOB object.
           * @return A pointer to an OOB object, if present, 0 otherwise.
           */
          const OOB* oob() const { return m_oob; }

          // reimplemented from StanzaExtension
          virtual const std::string& filterString() const;

          // reimplemented from StanzaExtension
          virtual StanzaExtension* newInstance( const Tag* tag ) const
          {
            return new Query( tag );
          }

          // reimplemented from StanzaExtension
          virtual Tag* tag() const;

          // reimplemented from StanzaExtension
          virtual StanzaExtension* clone() const
          {
            Query* q = new Query();
            q->m_form = m_form ? new DataForm( *m_form ) : 0;
            q->m_fields = m_fields;
            q->m_values = m_values;
            q->m_instructions = m_instructions;
            q->m_oob = new OOB( *m_oob );
            q->m_del = m_del;
            q->m_reg = m_reg;
            return q;
          }

        private:
          DataForm* m_form;
          int m_fields;
          RegistrationFields m_values;
          std::string m_instructions;
          OOB* m_oob;
          bool m_del;
          bool m_reg;
      };

  /**
       * Constructor.

       * @param parent 用于建立连接的ClientBase实体指针

       * @param parent The ClientBase which is used for establishing a connection.
       * @param to The server or service to authenticate with. If empty the currently connected
       * server will be used.
       */
      Registration( ClientBase* parent, const JID& to );

      /**
       * Constructor. Registration will be attempted with the ClientBase's connected host.
       * @param parent The ClientBase which is used for establishing a connection.
       */
      Registration( ClientBase* parent );

      /**
       * Virtual destructor.
       */
      virtual ~Registration();

      /**

       * 用这个函数去应答服务器所要求的注册字段

       * 被注册了RegistrationHandler 的对象（可以通过将RegistrationHandler 设置为该对象的一个成员变量注registerRegistrationHandler）   

       * 通过用 RegistrationHandler::handleRegistrationFields()应答异步返回的注册字段。
       * Use this function to request the registration fields the server requires.
       * The required fields are returned asynchronously to the object registered as
       * @ref RegistrationHandler by calling @ref RegistrationHandler::handleRegistrationFields().
       */
      void fetchRegistrationFields();

      /**
       * Attempts to register an account with the given credentials. Only the fields OR'ed in
       * @c fields will be sent. This can only be called with an unauthenticated parent (@ref Client).
       * @note It is recommended to use @ref fetchRegistrationFields to find out which fields the
       * server requires.
       * @param fields The fields to use to generate the registration request. OR'ed
       * @ref fieldEnum values.
       * @param values The struct contains the values which shall be used for the registration.
       * @return Returns @b true if the registration request was sent successfully, @b false
       * otherwise. In that case either there's no connected ClientBase available, or
       * prepping of the username failed (i.e. the username is not valid for use in XMPP).
       */
      bool createAccount( int fields, const RegistrationFields& values );

      /**
       * Attempts to register an account with the given credentials. This can only be called with an
       * unauthenticated parent (@ref Client).
       * @note According to XEP-0077, if the server sends both old-style fields and data form,
       * implementations SHOULD prefer data forms.
       * @param form The DataForm containing the registration credentials.
       */
      void createAccount( DataForm* form );

      /**
       * Tells the server to remove the currently authenticated account from the server.
       */
      void removeAccount();

      /**
       * Tells the server to change the password for the current account.
       * @param username The username to change the password for. You might want to use
       * Client::username() to get the current prepped username.
       * @param password The new password.
       */
      void changePassword( const std::string& username, const std::string& password );

      /**

       * 给这个Registration实体注册一个RegistrationHandler，这个对象只能有一个handler
       * Registers the given @c rh as RegistrationHandler. Only one handler is possible at a time.
       * @param rh The RegistrationHandler to register.
       */
      void registerRegistrationHandler( RegistrationHandler* rh );

      /**
       * Un-registers the current RegistrationHandler.
       */
      void removeRegistrationHandler();

      // reimplemented from IqHandler.
      virtual bool handleIq( const IQ& iq ) { (void)iq; return false; }

      // reimplemented from IqHandler.
      virtual void handleIqID( const IQ& iq, int context );

    private:
#ifdef REGISTRATION_TEST
    public:
#endif

      enum IdType
      {
        FetchRegistrationFields,
        CreateAccount,
        RemoveAccount,
        ChangePassword
      };

      Registration operator=( const Registration& );

      void init();

      ClientBase* m_parent;
      const JID m_to;
      RegistrationHandler* m_registrationHandler;
  };

}

未完。。。待续。。。