Signing In to a Server

The first action that most libjingle applications do over the network is to sign in to an XMPP server. The server acts as the central communication point for users to find each other and start initiating connections.

1. Initialize SSL if it is being used. See SSL Support for details.
2. Create the signaling thread. The simplest way is to create an AutoThread object, which captures the current operating system thread and makes it the current thread in ThreadManager.
3. Get login information from the user. XmppClientSettings holds the information required to sign in to an XMPP server, such as name, password, and server address.

Note: The example code uses SSL to transmit the password from the client to the XMPP server; however, it does not provide any additional security (except turning off screen echo) to protect the password on the client.

3. Create your XMPP task manager object. libjingle ships with XmppPump, a helper class that wraps XmppClient and handles signing in to a XMPP server. See the documentation for that class for a description of signing in. This is the manager for the XMPP messaging component, which handles all the XMPP tasks, such as sending or receiving presence notifications, and signing in to a server.
4. Connect to receive sign in progress notifications. Connect to the XmppPump object's SignalStateChange signal. This signal sends notifications about the progress of the sign in; when it sends a STATE_OPEN state, you have successfully signed in to the server.
5. Sign in to the server. Call XmppPump::DoLogin to sign in. The example code also specifies the Google Talk server as the XMPP server. You can change this in the buzz::XmppClientSettings value you pass into XmppPump::DoLogin. DoLogin requires a running signaling thread; the DoLogin call is queued and not started until you call Run on the signaling thread (described next).
6. Call Run on the signaling thread to keep the message thread listener looping indefinitely. Or, if you have your own method of causing the program to persist indefinitely, you can call Start instead.
7. Listen for success or failure messages. As mentioned previously, XmppPump will send STATE_OPEN when the application has signed in.
8. You will later have to request STUN and relay port information as described in Set Up the Session Management Pathway to pass to a PortAllocator object that you will instantiate in the next topic, Sending and Querying Presence.

Once you are signed in, you should send your presence to the server, and register to receive presence notifications for other roster members as described in Sending and Querying Presence.

Note: The example code signs in to the Google Talk server with a hard-coded address. If you want to sign in to a different server, you must change the host and server address values passed in to the server settings parameter of the XmppPump::DoLogin command.

The following (modified) code from the file share sample application demonstrates signing in to a server. The code has been reorganized and trimmed for clarity.

// Initialize SSL channel.
talk_base::InitializeSSL();

// Create the signaling thread.
// AutoThread captures the current OS thread and sets it to be
// ThreadManager::CurrentThread, which will be called and used by SessionManager 
talk_base::PhysicalSocketServer ss;
talk_base::AutoThread main_thread(&ss);

// Get the information we'll need to sign in.
XmppPump pump;
buzz::Jid jid;
buzz::XmppClientSettings xcs;
talk_base::InsecureCryptStringImpl pass;
std::string username;

// Read and verify the user's JID from the command-line.
std::cout << "JID: ";
std::cin >> username;
jid = buzz::Jid(username);
if (!jid.IsValid() || jid.node() == "") {
  printf("Invalid JID. JIDs should be in the form user@domain\n");
  return 1;
}

// Read the user's password (invisibly) from the screen.
SetConsoleEcho(false);
std::cout << "Password: ";
std::cin >> pass.password();
SetConsoleEcho(true);
std::cout << std::endl;

// Store the values required for signing in. These
// include jid, resource, name, and password.
// The example uses a hard-coded value to indicate the Google Talk 
// service.
xcs.set_user(jid.node());
xcs.set_resource("pcp");  // Arbitrary resource name.
xcs.set_host(jid.domain());
xcs.set_use_tls(true);
xcs.set_pass(talk_base::CryptString(pass));
xcs.set_server(talk_base::SocketAddress("talk.google.com", 5222));

// Sign up to receive signals from the XMPP pump to track sign in progress.
pump.client()->SignalStateChange.connect(&fs_client, &FileShareClient::OnStateChange);

// Queue up the sign in request.
pump.DoLogin(xcs, new XmppSocket(true), NULL);

// Start the thread and run indefinitely.
main_thread.Run();

...

// Function that receives sign in progress notifications.
void OnStateChange(buzz::XmppEngine::State state) {
  switch (state) {
    case buzz::XmppEngine::STATE_START:
      // Attempting sign in.
      break;
    case buzz::XmppEngine::STATE_OPENING:
      // Negotiating with server.
      break;
    case buzz::XmppEngine::STATE_OPEN:
      // Connection succeeded. Send your presence information.
      // and sign up to receive presence notifications.
      OnSignon();
      break;
    case buzz::XmppEngine::STATE_CLOSED:
      // Connection ended. 
      break;
  }
}