session.h

本人收集整理的一份c/c++跨平台网络库

/*
 * libjingle
 * Copyright 2004--2005, Google Inc.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 *  1. Redistributions of source code must retain the above copyright notice,
 *     this list of conditions and the following disclaimer.
 *  2. Redistributions in binary form must reproduce the above copyright notice,
 *     this list of conditions and the following disclaimer in the documentation
 *     and/or other materials provided with the distribution.
 *  3. The name of the author may not be used to endorse or promote products
 *     derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
 * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

#ifndef _SESSION_H_
#define _SESSION_H_

#include "talk/base/socketaddress.h"
#include "talk/p2p/base/sessiondescription.h"
#include "talk/p2p/base/sessionmanager.h"
#include "talk/p2p/base/sessionclient.h"
#include "talk/p2p/base/sessionid.h"
#include "talk/p2p/base/port.h"
#include "talk/xmllite/xmlelement.h"
#include <string>

namespace cricket {

class SessionManager;
class Transport;
class TransportChannel;
class TransportChannelProxy;
class TransportChannelImpl;

// A specific Session created by the SessionManager.  A Session manages
// signaling for session setup and tear down.  This setup includes negotiation
// of both the application-level and network-level protocols:  the former
// defines what will be sent and the latter defines how it will be sent.  Each
// network-level protocol is represented by a Transport object.  Each Transport
// participates in the network-level negotiation.  The individual streams of
// packets are represented by TransportChannels.
class Session : public talk_base::MessageHandler, public sigslot::has_slots<> {
 public:
  enum State {
    STATE_INIT = 0,
    STATE_SENTINITIATE,      // sent initiate, waiting for Accept or Reject
    STATE_RECEIVEDINITIATE,  // received an initiate. Call Accept or Reject
    STATE_SENTACCEPT,        // sent accept. begin connecting transport
    STATE_RECEIVEDACCEPT,    // received accept. begin connecting transport
    STATE_SENTMODIFY,        // sent modify, waiting for Accept or Reject
    STATE_RECEIVEDMODIFY,    // received modify, call Accept or Reject
    STATE_SENTREJECT,        // sent reject after receiving initiate
    STATE_RECEIVEDREJECT,    // received reject after sending initiate
    STATE_SENTREDIRECT,      // sent direct after receiving initiate
    STATE_SENTTERMINATE,     // sent terminate (any time / either side)
    STATE_RECEIVEDTERMINATE, // received terminate (any time / either side)
    STATE_INPROGRESS,        // session accepted and in progress
    STATE_DEINIT,            // session is being destroyed
  };

  enum Error {
    ERROR_NONE = 0, // no error
    ERROR_TIME,     // no response to signaling
    ERROR_RESPONSE, // error during signaling
    ERROR_NETWORK,  // network error, could not allocate network resources
  };

  // Returns the manager that created and owns this session.
  SessionManager* session_manager() const { return session_manager_; }

  // Returns the XML namespace identifying the type of this session.
  const std::string& session_type() const { return session_type_; }

  // Returns the client that is handling the application data of this session.
  SessionClient* client() const { return client_; }

  // Returns the JID this client.
  const std::string &name() const { return name_; }

  // Returns the JID of the other peer in this session.
  const std::string &remote_name() const { return remote_name_; }

  // Indicates whether we initiated this session.
  bool initiator() const { return initiator_; }

  // Holds the ID of this session, which should be unique across the world.
  const SessionID& id() const { return id_; }

  // Returns the applicication-level description given by our client.  This
  // will be null until Initiate or Accept.
  const SessionDescription *description() const { return description_; }

  // Returns the applicication-level description given by the other client.
  // If we are the initiator, this will be null until we receive an accept.
  const SessionDescription *remote_description() const {
    return remote_description_;
  }

  // Returns the current state of the session.  See the enum above for details.
  // Each time the state changes, we will fire this signal.
  State state() const { return state_; }
  sigslot::signal2<Session *, State> SignalState;

  // Fired whenever we receive a terminate message along with a reason
  sigslot::signal2<Session *, const std::string &> SignalReceivedTerminateReason;

  // Returns the last error in the session.  See the enum above for details.
  // Each time the an error occurs, we will fire this signal.
  Error error() const { return error_; }
  sigslot::signal2<Session *, Error> SignalError;

  // Returns the transport that has been negotiated or NULL if negotiation is
  // still in progress.
  Transport* transport() const { return transport_; }

  // When a session was created by us, we are the initiator, and we send the
  // initiate message when this method is invoked.  The extra_xml parameter is
  // a list of elements that will get inserted inside <Session> ... </Session>
  bool Initiate(const std::string &to, std::vector<buzz::XmlElement*>* extra_xml, 
                const SessionDescription *description);

  // When we receive a session initiation from another client, we create a
  // session in the RECEIVEDINITIATE state.  We respond by accepting,
  // rejecting, or redirecting the session somewhere else.
  bool Accept(const SessionDescription *description);
  bool Reject();
  bool Redirect(const std::string& target);

  // At any time, we may terminate an outstanding session.
  bool Terminate();

  // The two clients in the session may also send one another arbitrary XML
  // messages, which are called "info" messages.  Both of these functions take
  // ownership of the XmlElements and delete them when done.
  typedef std::vector<buzz::XmlElement*> XmlElements;
  void SendInfoMessage(const XmlElements& elems);
  sigslot::signal2<Session*, const XmlElements&> SignalInfoMessage;

  // Controls the set of transports that will be allowed for this session.  If
  // we are initiating, then this list will be used to construct the transports
  // that we will offer to the other side.  In that case, the order of the
  // transport names indicates our preference (first has highest preference).
  // If we are receiving, then this list indicates the set of transports that
  // we will allow.  We will choose the first transport in the offered list
  // (1) whose name appears in the given list and (2) that can accept the offer
  // provided (which may include parameters particular to the transport).
  //
  // If this function is not called (or if it is called with a NULL array),
  // then we will use a default set of transports.
  void SetPotentialTransports(const std::string names[], size_t length);

  // Once transports have been created (by SetTransports), this function will
  // return the transport with the given name or NULL if none was created.
  // Once a particular transport has been chosen, only that transport will be
  // returned.
  Transport* GetTransport(const std::string& name);

  // Creates a new channel with the given name.  This method may be called
  // immediately after creating the session.  However, the actual
  // implementation may not be fixed until transport negotiation completes.
  TransportChannel* CreateChannel(const std::string& name);

  // Returns the channel with the given name.
  TransportChannel* GetChannel(const std::string& name);

  // Destroys the given channel.