Registration Class Reference

`#include <registration.h>`

Inheritance diagram for Registration:
[legend]

## Classes

class | Query

## Public Types

enum | fieldEnum { FieldUsername = 1 , FieldNick = 2 , FieldPassword = 4 , FieldName = 8 , FieldFirst = 16 , FieldLast = 32 , FieldEmail = 64 , FieldAddress = 128 , FieldCity = 256 , FieldState = 512 , FieldZip = 1024 , FieldPhone = 2048 , FieldUrl = 4096 , FieldDate = 8192 , FieldMisc = 16384 , FieldText = 32768 }

## Public Member Functions

| Registration (ClientBase *parent, const JID &to)
| Registration (ClientBase *parent)
virtual | ~Registration ()
void | fetchRegistrationFields ()
bool | createAccount (int fields, const RegistrationFields &values)
void | createAccount (DataForm *form)
void | removeAccount ()
void | changePassword (const std::string &username, const std::string &password)
void | registerRegistrationHandler (RegistrationHandler *rh)
void | removeRegistrationHandler ()
virtual bool | handleIq (const IQ &iq)
virtual void | handleIqID (const IQ &iq, int context)
Public Member Functions inherited from IqHandler
virtual | ~IqHandler ()

## Detailed Description

This class is an implementation of XEP-0077 (In-Band Registration).

Derive your object from RegistrationHandler and implement the virtual functions offered by that interface. Then use it like this:

void MyClass::myFunc()
{
m_client = new Client( "example.org" );
m_client->disableRoster(); // a roster is not necessary for registration
m_client->registerConnectionListener( this );
m_reg = new Registration( c );
m_reg->registerRegistrationHandler( this );
m_client->connect();
}
void MyClass::onConnect()
{
m_reg->fetchRegistrationFields();
}
gloox::Client
This class implements a basic Jabber/XMPP Client.
Definition client.h:117
gloox::Registration::Registration
Registration(ClientBase *parent, const JID &to)
Definition registration.cpp:219

In RegistrationHandler::handleRegistrationFields() you should check which information the server requires to open a new account. You might not always get away with just username and password. Then call createAccount() with a filled-in RegistrationFields and an `int` representing the bit-wise ORed fields you want to have included in the registration attempt. For your convenience you can use the 'fields' argument of handleRegistrationFields(). ;) It's your responsibility to make sure at least those fields the server requested are filled in.

Check `tests/register_test.cpp` for an example.

Author
  Jakob Schröter js@ca.nosp@m.maya.nosp@m..net

Since
  0.2

Definition at line 92 of file registration.h.

## Member Enumeration Documentation

## fieldEnum

enum fieldEnum

The possible fields of a XEP-0077 account registration.

Enumerator
FieldUsername | Username requested
FieldNick | Nickname requested
FieldPassword | Password requested
FieldName | Name requested
FieldFirst | Given name requested
FieldLast | Family name requested
FieldEmail | Email address requested
FieldAddress | Postal address requested
FieldCity | Locality requested
FieldState | State/Province requested
FieldZip | ZIP requested
FieldPhone | Phone no. requested
FieldUrl | Homepage or other URL requested
FieldDate | Date requested (unknown purpose; see XEP-0077)
FieldMisc | Misc data requested (unknown purpose; see XEP-0077)
FieldText | Extra text requested (unknown purpose; see XEP-0077)

Definition at line 99 of file registration.h.

## Constructor & Destructor Documentation

## Registration() [1/2]

Registration | ( | ClientBase * | parent,
|  | const JID & | to )

Constructor.

Parameters

  parent | The ClientBase which is used for establishing a connection.
  to | The server or service to authenticate with. If empty the currently connected server will be used.

Definition at line 219 of file registration.cpp.

## Registration() [2/2]

Registration | ( | ClientBase * | parent | ) |

Constructor. Registration will be attempted with the ClientBase's connected host.

Parameters

  parent | The ClientBase which is used for establishing a connection.

Definition at line 225 of file registration.cpp.

## ~Registration()

~Registration | ( |  | ) |

virtual

Virtual destructor.

Definition at line 240 of file registration.cpp.

## Member Function Documentation

## changePassword()

void changePassword | ( | const std::string & | username,
|  | const std::string & | password )

Tells the server to change the password for the current account.

Parameters

  username | The username to change the password for. You might want to use Client::username() to get the current prepped username.
  password | The new password.

Definition at line 293 of file registration.cpp.

## createAccount() [1/2]

void createAccount | ( | DataForm * | form | ) |

Attempts to register an account with the given credentials. This can only be called with an unauthenticated parent (Client).

Note
  According to XEP-0077, if the server sends both old-style fields and data form, implementations SHOULD prefer data forms.

Parameters

  form | The DataForm containing the registration credentials.

Definition at line 273 of file registration.cpp.

## createAccount() [2/2]

bool createAccount | ( | int | fields,
|  | const RegistrationFields & | values )

Attempts to register an account with the given credentials. Only the fields OR'ed in `fields` will be sent. This can only be called with an unauthenticated parent (Client).

Note
  It is recommended to use fetchRegistrationFields to find out which fields the server requires.

Parameters

  fields | The fields to use to generate the registration request. OR'ed fieldEnum values.
  values | The struct contains the values which shall be used for the registration.

Returns
  Returns true if the registration request was sent successfully, 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).

Definition at line 260 of file registration.cpp.

## fetchRegistrationFields()

void fetchRegistrationFields | ( |  | ) |

Use this function to request the registration fields the server requires. The required fields are returned asynchronously to the object registered as RegistrationHandler by calling handleRegistrationFields().

Definition at line 250 of file registration.cpp.

## handleIq()

virtual bool handleIq | ( | const IQ & | iq | ) |

inline virtual

Reimplement this function if you want to be notified about incoming IQs.

Parameters

  iq | The complete IQ stanza.

Returns
  Indicates whether a request of type 'get' or 'set' has been handled. This includes the obligatory 'result' answer. If you return false, an 'error' will be sent back.

Since
  1.0

Implements IqHandler.

Definition at line 310 of file registration.h.

## handleIqID()

void handleIqID | ( | const IQ & | iq,
|  | int | context )

virtual

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 empty positive reply, i.e. <iq type='result' id='reg'/> where a namespace filter wouldn't work.

Parameters

  iq | The complete IQ stanza.
  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

Implements IqHandler.

Definition at line 315 of file registration.cpp.

## registerRegistrationHandler()

void registerRegistrationHandler | ( | RegistrationHandler * | rh | ) |

Registers the given `rh` as RegistrationHandler. Only one handler is possible at a time.

Parameters

  rh | The RegistrationHandler to register.

Definition at line 305 of file registration.cpp.

## removeAccount()

void removeAccount | ( |  | ) |

Tells the server to remove the currently authenticated account from the server.

Definition at line 283 of file registration.cpp.

## removeRegistrationHandler()

void removeRegistrationHandler | ( |  | ) |

Un-registers the current RegistrationHandler.

Definition at line 310 of file registration.cpp.

The documentation for this class was generated from the following files:

- registration.h
- registration.cpp