这里涉及到几个类:
一.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>
* 密码修改:服务器认为通道的安全程度不足以保证密码的修改
{
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, /**帐户移除:
* the channel safe enough to enable a password change. */
RegistrationBadRequest, /**帐户移除:
*< Account removal: The <remove/> element was not
* the only child element of the <query/> element.
* Should not happen when only gloox functions are being
* used.<br>
* the only child element of the <query/> element.
* Should not happen when only gloox functions are being
* used.<br>
*密码修改:不包含完整的密码修改要求的信息
* Password change: The password change request does not
* contain complete information (both <username/> and
* <password/> 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. */
};
* Password change: The password change request does not
* contain complete information (both <username/> and
* <password/> 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() {}
{
public:
virtual ~RegistrationHandler() {}
/**
*重新实现这个函数去接收Registration::fetchRegistrationFields() 返回的结果
* Reimplement this function to receive results of the
* @ref Registration::fetchRegistrationFields() function.
* 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 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 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;
* @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;
* 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 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;
* 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;
* 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() {}
{
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;
* 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;
* 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:
{
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 );
{
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 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 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 );
* Creates a new object from the given Tag.
* @param tag The Tag to parse.
*/
Query( const Tag* tag );
/**
* Virtual Destructor.
*/
virtual ~Query();
* 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 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 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; }
* Returns the registration fields, if set.
* @return The registration fields.
*/
int fields() const { return m_fields; }
/**
*
*/
const RegistrationFields& values() const { return m_values; }
*
*/
const RegistrationFields& values() const { return m_values; }
/**
* Indicates whether the account is already registered.
* @return @b True if the <registered> element is present, @b false otherwise.
*/
bool registered() const { return m_reg; }
* Indicates whether the account is already registered.
* @return @b True if the <registered> element is present, @b false otherwise.
*/
bool registered() const { return m_reg; }
/**
* Indicates whether the account shall be removed.
* @return @b True if the <remove> element is present, @b false otherwise.
*/
bool remove() const { return m_del; }
* Indicates whether the account shall be removed.
* @return @b True if the <remove> 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; }
* 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;
virtual const std::string& filterString() const;
// reimplemented from StanzaExtension
virtual StanzaExtension* newInstance( const Tag* tag ) const
{
return new Query( tag );
}
virtual StanzaExtension* newInstance( const Tag* tag ) const
{
return new Query( tag );
}
// reimplemented from StanzaExtension
virtual Tag* tag() const;
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;
}
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;
};
DataForm* m_form;
int m_fields;
RegistrationFields m_values;
std::string m_instructions;
OOB* m_oob;
bool m_del;
bool m_reg;
};
/**
* Constructor.
* 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 );
* @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 );
* 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();
* 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();
* 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. 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 );
* 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 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 );
* 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 );
* 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();
* Un-registers the current RegistrationHandler.
*/
void removeRegistrationHandler();
// reimplemented from IqHandler.
virtual bool handleIq( const IQ& iq ) { (void)iq; return false; }
virtual bool handleIq( const IQ& iq ) { (void)iq; return false; }
// reimplemented from IqHandler.
virtual void handleIqID( const IQ& iq, int context );
virtual void handleIqID( const IQ& iq, int context );
private:
#ifdef REGISTRATION_TEST
public:
#endif
#ifdef REGISTRATION_TEST
public:
#endif
enum IdType
{
FetchRegistrationFields,
CreateAccount,
RemoveAccount,
ChangePassword
};
{
FetchRegistrationFields,
CreateAccount,
RemoveAccount,
ChangePassword
};
Registration operator=( const Registration& );
void init();
ClientBase* m_parent;
const JID m_to;
RegistrationHandler* m_registrationHandler;
};
const JID m_to;
RegistrationHandler* m_registrationHandler;
};
}
未完。。。待续。。。