chat_connection.h

Go to the documentation of this file.

#ifndef CHAT_API_CLASS
#define CHAT_API_CLASS

/*****************************************************************************\
*                                                                             *
*  Name   : chat_connection                                                   *
*  Author : Chris Koeritz                                                     *
*                                                                             *
*  Purpose:                                                                   *
*                                                                             *
*    Provides an interface to chat services.  This allows a user to send text *
*  messages as well as files and other objects to a correspondent.            *
*                                                                             *
*******************************************************************************
* Copyright (c) 2000-$now By Author.  This program is free software; you can  *
* redistribute it and/or modify it under the terms of the GNU General Public  *
* License as published by the Free Software Foundation; either version 2 of   *
* the License or (at your option) any later version.  This is online at:      *
*     http://www.fsf.org/copyleft/gpl.html                                    *
* Please send any updates to: fred@gruntose.com                               *
\*****************************************************************************/

#include "buzz_dll.h"

#include <sockets/definitions_sockets.h>

// forward.
class communicator;
class extended_address;
class filename;
class transport;

class BUZZ_CLASS_STYLE chat_connection
{
public:
  enum chat_capabilities {
    SEND_TEXT = 0x1,   // all chat connections should support this.
    SEND_FILE = 0x2,   // many chat connections can support this.  if initially
                       // it is not supported, try using the renegotiate()
                       // method to get the other side to allow it.
  }; 

  chat_connection(communicator &commlink, const extended_address &where,
          int capabilities);
    // makes a connection to the location "where", which can use any supported
    // network address type and mode.  the health of the connection can be
    // tested with the connected() method.  the "capabilities" should be a
    // bitwise OR of the chat_capabilities that you wish to allow.  this list
    // can be changed on this side with the capabilities() modification method
    // and on the other side with the renegotiate() method.  the "commlink"
    // must be provided and must exist through the lifetime of the chat.

  virtual ~chat_connection();
    // terminates the chat and shuts down the connection.

  enum outcomes {
    OKAY = common::OKAY,

    NO_CONNECTION = communication_commons::NO_CONNECTION,

    DEFINE_OUTCOME(NO_CAPABILITY, -66, "The connection does not support "
        "this currently"),
  };

  const char *outcome_name(const outcome &outcome) const;
    // returns the name for the "outcome" specified.

  bool connected() const;
    // returns true if the connection appears healthy.

  // observes or modifies the path where downloaded files will be stored.
  // if this is a bad path, then no files can be downloaded.
  filename download_path() const;
  void download_path(const filename &path);

  // capability management:

  int capabilities() const;
    // returns the current set of capabilities for this chat connection as
    // a bit-wise ORed integer.  testing using the chat_capabilities will
    // tell if a particular capability is enabled.
  void capabilities(int new_capabilities);
    // modifies the set of capabilities we allow on this side.

  outcome renegotiate(int new_capability);
    // asks the other side if it will enable the new connection of
    // capabilities specified in the "new_capability".  don't forget to OR
    // in all the current capabilities that you want as well as the new ones;
    // if a capability is omitted from the new value and this call succeeds,
    // then you will have less power than before.

  // worker functions.

  outcome send_string(const istring &to_send);
    // sends a textual message "to_send" to the other side.

  outcome send_file(const istring &filename);
    // transmits a file pointed at by the "filename" to the other side.  this
    // will only work if the connection supports the SEND_FILE capability.

  bool get_string(istring &received);
    // retrieves the next textual message into "received".  true is returned if
    // a message was available.

  bool get_file(istring &path);
    // retrieves the next file that is available to the default download area
    // and stores the full path to the file in "path".

  // alert functions; over-ride to hear the announcements.

  virtual void renegotiation();
    // invoked when the capabilities have changed, either by one's own request
    // or by the other side's request.

  virtual void data_ready();
    // either a text message is ready or there is a file waiting.

private:
  transport *_sender;  // the communication support we use for sending.
  transport *_receiver;  // the communication support we use for receptions.

  // not permitted.
  chat_connection(chat_connection &);
  chat_connection &operator =(chat_connection &);
};

#endif

---