address.h

Go to the documentation of this file.

#ifndef NETWORK_ADDRESS_CLASS
#define NETWORK_ADDRESS_CLASS

/*****************************************************************************\
*                                                                             *
*  Name   : network_address                                                   *
*  Author : Chris Koeritz                                                     *
*                                                                             *
*  Purpose:                                                                   *
*                                                                             *
*    Provides a way to describe the destination for messages that will        *
*  be sent through the different kinds of transport mechanisms; a             *
*  network_address represents a location on some communications medium.       *
*                                                                             *
*******************************************************************************
* Copyright (c) 1995-$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 "address_base.h"

// forward.
class configurator;
class machine_uid;

// The ideal goal here is to not include any network specific header files:
// The address should be stated in terms of the simpler characteristics of the
// underlying kind of transport address and should include all relevant
// constants.  Only the actual derived classes should include details
// from the communications-medium dependent interfaces.


class SOCKETS_CLASS_STYLE internet_address : public address_base
{
public:
  enum internet_address_constraints {
    ADDRESS_SIZE = 4,
    MAXIMUM_HOSTNAME_LENGTH = 128
  };

  typedef byte address_array[ADDRESS_SIZE];
  address_array ip_address;
  int port;

  char hostname[MAXIMUM_HOSTNAME_LENGTH];
    // can be resolved to an ip_address if a domain name server
    // is available.

  internet_address();
  internet_address(const byte_array &ip_address, const istring &host,
          int port);

  IMPLEMENT_CLASS_NAME("internet_address");

  machine_uid convert() const;
    // returns the address in the uniquifying format.

  void fill(const byte_array &ip_address, const istring &host, int port);

  bool same_host(const address_base &to_compare) const;
  bool same_port(const address_base &to_compare) const;
  bool shareable(const address_base &to_compare) const;

  inline bool operator == (const internet_address &to_compare) const {
    return same_host(to_compare) && same_port(to_compare);
  }

  istring text_form() const;

  istring tokenize() const;
  bool detokenize(const istring &info);

  istring normalize_host() const;
    // returns a normal form for the hostname or address.  this will come from
    // the hostname member first, if it's set.  next it will come from the
    // string form of the IP address.

  static const byte_array &nil_address();
    // returns the address that is all zeros, otherwise known as INADDR_ANY.

  bool is_nil_address() const;
    // returns true if this object's address_array is all zeros.

  static bool is_nil_address(const address_array &ip_address);
    // returns true if the array "ip_address" is all zero.

  static bool valid_address(const istring &to_check);
    // returns true if the address "to_check" seems well-formed for IP.  note
    // that this will accept 0.0.0.0 as valid.

  static bool is_valid_internet_address(const istring &to_check,
          byte_array &ip_form, bool &all_zeros);
    // this function checks the string "to_check" to see if it is a valid
    // internet address (e.g., 143.203.39.222).  if it is a valid address,
    // then the address "ip_form" is filled in with four bytes that are each
    // in the range (0..255).  if the "ip_form" is 0.0.0.0, then all_zeros
    // is set to true.

  static bool ip_appropriate_number(const istring &to_check, int indy,
          istring &accum);

  static bool has_ip_address(const istring &to_check, istring &ip_found);

  static istring ip_address_text_form(const byte_array &ip_address);
    // returns a string containing the textual form of the "ip_address".  the
    // "ip_address" is expected to have the proper length (four bytes).  if it
    // does not, then an empty string is returned.

  static const byte_array &localhost();
    // provides the array that indicates localhost, rather than a NIC.
    // this is commonly known to be 127.0.0.1.

  bool is_localhost() const;
    // returns true if the address in question is the same as the localhost,
    // either through the name matching "local" or "localhost", or through
    // the address matching 127.0.0.1.  note that the word "local" here is
    // an "enhancement" and would not normally be considered the same as
    // localhost.  beware a networked computer that's actually named "local".
    // also note that an address where the name disagrees with the address is
    // basically broken, but we are not checking that here; either condition
    // of the hostname or the address matching causes this to return true.

  address_base *create_copy() const;

  void pack(byte_array &packed_form) const;
  bool unpack(byte_array &packed_form);

  virtual int packed_size() const;
};

#ifndef EMBEDDED_BUILD


class SOCKETS_CLASS_STYLE serial_port_address : public address_base
{
public:
  enum parity_type
      { NONE = 'N', EVEN = 'E', ODD = 'O', MARK = 'M', SPACE = 'S' };

  enum stop_bits_type {
    ZERO_SB = 0,
    ONE_SB = 1,
    ONE_POINT_FIVE_SB = 9,
    TWO_SB = 2
  };

  int port;   // range from 1 .. n for COM1 .. COMn.
  int baud_rate;
  byte data_bits;
  char parity;  // use the parity_type above.
  byte stop_bits;  // use the stop_bits_type above.

  serial_port_address();
  serial_port_address(int port, int baud_rate, byte data_bits, char parity,
      byte stop_bits);

  void fill(int port, int baud_rate, byte data_bits, char parity,
      byte stop_bits);

  IMPLEMENT_CLASS_NAME("serial_port_address");

  bool same_host(const address_base &to_compare) const;
  bool same_port(const address_base &to_compare) const;
  bool shareable(const address_base &to_compare) const;

  istring text_form() const;

  istring tokenize() const;
  bool detokenize(const istring &info);

  address_base *create_copy() const;

  void pack(byte_array &packed_form) const;
  bool unpack(byte_array &packed_form);

  virtual machine_uid convert() const;

  virtual int packed_size() const;

  // commands understood by serial_transports.  note that "now" is relative to
  // when the command is processed.  if the transport is in streaming mode,
  // then the command will hit after any messages that were scheduled before
  // the command.
  static istring GET_DSR();  // the DSR state as of "now" is returned.
  static istring GET_CTS();  // the CTS state ....
  static istring SET_DTR();  // sets the DTR state to value found in command.
  static istring SET_RTS();  // sets the RTS state ....
  static istring USE_MARK_SPACE();
    // invokes the special mark-space parity protocol for the message to be
    // transferred after this one; the first byte is transmitted with mark
    // parity and the rest are transmitted with space parity.
};


class SOCKETS_CLASS_STYLE ipc_address : public address_base
{
public:
  enum ipc_address_constraints {
    MAXIMUM_IPC_NAME_LENGTH = 42
  };

  char service[MAXIMUM_IPC_NAME_LENGTH];
  char topic[MAXIMUM_IPC_NAME_LENGTH];

  ipc_address();
  ipc_address(const istring &service, const istring &topic);

  void fill(const istring &service, const istring &topic);

  bool same_host(const address_base &to_compare) const;
  bool same_port(const address_base &to_compare) const;
  bool shareable(const address_base &to_compare) const;

  istring text_form() const;

  IMPLEMENT_CLASS_NAME("ipc_address");

  istring tokenize() const;
  bool detokenize(const istring &info);

  virtual machine_uid convert() const;

  address_base *create_copy() const;

  void pack(byte_array &packed_form) const;
  bool unpack(byte_array &packed_form);

  virtual int packed_size() const;
};

#endif // embedded


// the unifying class: network_address pulls together the other types..

class SOCKETS_CLASS_STYLE network_address : public packable
{
public:
  network_address();
  network_address(const network_address &to_copy);

  network_address(const internet_address &address);
#ifndef EMBEDDED_BUILD
  network_address(const serial_port_address &address);
  network_address(const ipc_address &address);
#endif

  ~network_address();

  IMPLEMENT_CLASS_NAME("network_address");

  network_address &operator =(const network_address &to_copy);

  // the address_type represents the networks and devices over which
  // communication is possible.
  enum address_type {
    ADDRESS_SENTINEL_BEGIN = 0,
    UNINITIALIZED_ADDRESS = 0,
    INVALID_ADDRESS = UNINITIALIZED_ADDRESS,
    IPC_ADDRESS,
    INTERNET_ADDRESS,
    SERIAL_PORT_ADDRESS,
    ADDRESS_SENTINEL_END
  };

  bool valid() const;
    // returns true if the type for this address is not UNINITIALIZED_ADDRESS.

  inline const char *type_name() const {
    return (_type == UNINITIALIZED_ADDRESS)? "UninitializedAddress"
        : _addr->class_name();
  }

  address_type type() const { return address_type(_type); }
  static istring text_for_type(address_type type);
  static address_type type_from_text(const istring &text);

  // the following accessor functions will return NIL if the type of
  // address requested doesn't match the type held internally.  these are
  // pointers to the internal contents and MUST NOT be destroyed.
  internet_address *internet();
  const internet_address *internet() const;
#ifndef EMBEDDED_BUILD
  serial_port_address *serial();
  const serial_port_address *serial() const;
  ipc_address *ipc();
  const ipc_address *ipc() const;
#endif

  bool comparable(address_type a, address_type b) const;
    // returns true if it is meaningful to compare two addresses.  for example,
    // it is meaningful to compare serial with modem, but not ipc or tcpip.
  bool same_host(const network_address &to_compare) const;
    // returns true if the hosts of this and "to_compare" are identical within
    // the networking scheme.
  bool same_port(const network_address &to_compare) const;
    // returns true if the posts of this and "to_compare" are identical within
    // the networking scheme.
  bool operator == (const network_address &to_compare) const;
    // returns true if the address "to_compare" is effectively identical to
    // this (that is, if it's host and port are the same).
  bool operator != (const network_address &to_compare) const
        { return !(*this == to_compare); }
  bool shareable(const network_address &to_compare) const;
    // returns true if the two transports can be shared.  this is false if the
    // two addresses are not == to each other.  it also fails if for some
    // reason the two addresses are not shareable due to communications medium
    // constraints.

  istring text_form(bool show_type = true) const;
    // returns a printed form of the address.  if "show_type" is true, then the
    // address_type is included.  otherwise, just the low level address is
    // printed.

  istring tokenize() const;
  bool detokenize(const istring &info);
    // converts the address to and from a specific text format.  if tokenize
    // fails, an empty string is returned.  if detokenize fails, false is
    // returned.

  static network_address load(configurator &config, const istring &section,
        const istring &name, const network_address &default_address);
    // retrieves the network address from "config" that is stored under the
    // "section" for the "name" specified.  the returned address will be
    // the same as "default_address" if no entry was found, and the "config"
    // will be updated to that default.  if a badly formed address is found
    // under the "name", then the return value's type() is uninitialized.
  static bool store(configurator &config, const istring &section,
        const istring &name, const network_address &to_store);
    // writes a network_address "to_store" to the "config" under the
    // "section" with the specified "name".

  // expensive packing using strings.
  void parse_pack(byte_array &packed_form) const;
  bool parse_unpack(byte_array &packed_form);

  machine_uid convert() const;
    // convert to our lower-level unique machine identifier.

  istring unified_hostname() const;
    // returns a string that represents the host's name uniquely.  if the
    // member is not set, the address is substituted.

  virtual int packed_size() const;

  // cheap packing by the ints and bytes.
  void pack(byte_array &packed_form) const;
  bool unpack(byte_array &packed_form);

private:
  int _type;  // what kind of address this is.
  address_base *_addr;  // our real data for the address.
};

#endif

---