Signals

t, Hangouts, in May 2013. Hangouts will replace Google Talk and does not support XMPP.

• Overview
• libjingle Guide
• Introduction
• Changelist
• Important Concepts
• How libjingle Applications Work
• Creating a libjingle Application
• Signing In to a Server
• Sending and Querying Presence
• Set Up the Session Management Pathway
• Making and Receiving Connections
• Scenarios
• Google Talk XMPP Extensions
• Introduction
• User Settings
• Off the Record Chats
• Jingle Server Discovery
• Gmail Notifications
• Shared Status Messages
• Extended Contact Attributes
• JID Domain Discovery
• Voicemail
• OAuth 2.0 Authorization

• 目录
• Signals
• Threads
• Naming Conventions
• SSL Support
• Connections
• Transports, Channels,and Connections
• Candidates
• Data Packets

Important Concepts

You should understand the following important concepts about libjingle:

• Signals
• Threads and Messages
• Naming Conventions
• SSL Support
• Connections
• Transports, Channels, and Connections
• Candidates
• Data Packets

Signals

libjingle uses the sigslot library to facilitate communication between objects. sigslot is a generic framework that enables you to connect a calling member to a receiving function in any class (including the same class) very simply. The way it works is this:

1. The sending class declares a member variable, called a signal, using a special template-like syntax. This signal defines the parameters of the listening function.
2. The listening class implements a function with the same number, type, and sequence of parameters as the signal. This is sometimes called the receiver or the slot. (Note: this can even be the same class as the one that declared the signal.) This function cannot return a value (e.g., returns void). The receiver must inheritsigslot::has_slots<>.
3. The listener connects to the signal by calling the signal's connect method, passing in a pointer to the instance of the listening object, and the address of the implementing class function.
4. The sender calls its signal member as if it were a function, passing in the appropriate parameter types as declared. It can pass parameters by either value or reference.

You can connect as many signals as you like to a common slot. libjingle sometimes assigns multiple signals to a single slot in order to consolidate its message handling. Conversely, several objects declare a signal object in order to broadcast commonly needed messages from a single point (for example, alerts sent when a connection state changes). sigslot takes care of disconnecting callbacks and dereferencing when objects are destroyed.

The following code demonstrates using sigslot:

// Class that sends the notification.
class Sender  {

  // The signal declaration. 
  // The '2' in the name indicates the number of parameters. Parameter types 
  // are declared in the template parameter list.
  sigslot::signal2<string message, std::time_t time> SignalDanger;

  // When anyone calls Panic(), we will send the SignalDanger signal.
  void Panic(){
    SignalDanger("Help!", std::time(0)); 
  }
 
 // Listening class. It must inherit sigslot.
class Receiver : public sigslot::has_slots<>{

  // Receiver registers to get SignalDanger signals.
  // When SignalDanger is sent, it is caught by OnDanger().
  // Second parameter gives address of the listener function class definition.
  // First parameter points to instance of this class to receive notifications.
  Receiver(Sender sender){ 
        sender->SignalDanger.connect(this, &Receiver.OnDanger);
  }

  // When anyone calls Panic(), Receiver::OnDanger gets the message.
  // Notice that the number and type of parameters match
  // those in Sender::SignalDanger, and that it doesn't return a value.
  void OnDanger(string message, std::time_t time){
    if(message == "Help!")
    { 
      // Call the police
      ...
    }
  }
...
}

Many classes in the code send signals to notify listeners of important events. For example, Call::SignalSessionStatesends notifications when you send or receive a connection attempt. Your application must connect to these signals and act appropriately.

The general convention in libjingle code is to prefix the name of a signal with Signal: e.g., SignalStateChange, SignalSessionState, SignalSessionCreate. Listener methods intended to connect to signals are typically prefixed withOn, e.g., OnPortDestroyed(), OnOutgoingMessage(), OnSendPacket().

See the sigslot documentation for more details.