octopi/library/sockets/tcpip_stack.h

   1 #ifndef TCPIP_STACK_GROUP
   2 #define TCPIP_STACK_GROUP
   3
   4 /*
   5 Name   : tcpip_stack
   6 Author : Chris Koeritz
   7 *******************************************************************************
   8 * Copyright (c) 1991-$now By Author.  This program is free software; you can  *
   9 * redistribute it and/or modify it under the terms of the GNU General Public  *
  10 * License as published by the Free Software Foundation; either version 2 of   *
  11 * the License or (at your option) any later version.  This is online at:      *
  12 *     http://www.fsf.org/copyleft/gpl.html                                    *
  13 * Please send any updates to: fred@gruntose.com                               *
  14 \*****************************************************************************/
  15
  16 #include "tcpip_definitions.h"
  17
  18 #include <basis/byte_array.h>
  19 #include <basis/contracts.h>
  20 #include <structures/string_array.h>
  21
  22 // forward declarations.
  23 struct sockaddr;
  24
  25 namespace sockets {
  26
  27 // forward declarations.
  28 class internet_address;
  29 class machine_uid;
  30 class machine_uid_array;
  31
  32 //! Helpful functions for interacting with TCP/IP stacks.
  33 /*!
  34   This class hides details of the platform specifics of the stack.
  35 */
  36
  37 class tcpip_stack : public virtual basis::root_object
  38 {
  39 public:
  40   tcpip_stack();
  41   virtual ~tcpip_stack();
  42
  43   bool healthy() const { return _healthy; }
  44     // returns true if the stack seems to be functioning properly.
  45
  46   DEFINE_CLASS_NAME("tcpip_stack");
  47
  48   static basis::astring tcpip_error_name(int error_value);
  49     // returns the name for the "error_value" specified, according to the
  50     // WinSock 1.1 specification.
  51
  52   basis::astring hostname() const;
  53     // gets the string form of the host's name for tcp/ip.
  54
  55   machine_uid this_host(int location_type) const;
  56     // returns the unique identifier of "this" host given the "location_type"
  57     // of interest.  the type should be a member of the machine_uid::
  58     // known_location_types enum.
  59
  60   static sockaddr convert(const internet_address &to_convert);
  61     // returns a low-level address created from our style of address.
  62   static internet_address convert(const sockaddr &to_convert);
  63     // returns our style address from the low-level address.
  64
  65   basis::byte_array full_resolve(const basis::astring &hostname, basis::astring &full_host) const;
  66     // finds the ip address for a "hostname".  the array will have zero
  67     // length on failure.  on success, the "full_host" will have the
  68     // possibly more authoratitative name for the host.
  69
  70   bool resolve_any(const basis::astring &name, internet_address &resolved) const;
  71     // translates "name" into a resolved form, where "name" can be either a
  72     // hostname or an ip address.  true is returned on success.
  73
  74   basis::astring dns_resolve(const basis::astring &hostname) const;
  75     // returns a string form of the IP address for "hostname" or an empty
  76     // string if hostname cannot be found.
  77
  78   bool enumerate_adapters(structures::string_array &ip_addresses, bool add_local = false) const;
  79     // returns a list of the ip addresses that TCP/IP reports for this machine.
  80     // if there's more than one address, then this machine is multi-homed,
  81     // which could be due to an active dialup networking session or due to
  82     // there being more than one network interface.  if the function returns
  83     // false, then tcp/ip failed to report any addresses at all.  if the
  84     // "add_local" parameter is true, then the localhost IP address is added
  85     // to the list also.
  86
  87   internet_address fill_and_resolve(const basis::astring &machine, int port,
  88           bool &worked) const;
  89     // creates an address for TCP/IP given the "machine" and the "port".
  90     // the "machine" can either be in dotted number notation or can be a
  91     // hostname.  a special value of "local" or the empty string in "machine"
  92     // causes _this_ host to be used in the address.  otherwise, if the
  93     // "machine" is a textual hostname, then it is plugged into the returned
  94     // address and resolved if possible.  if the resolution of the "machine"
  95     // is successful, then "worked" is set to true.
  96
  97   bool enumerate_adapters(machine_uid_array &ip_addresses,
  98           bool add_local = false) const;
  99     // similar to other function of same name but provides a list of
 100     // machine_uid objects.
 101
 102 private:
 103   bool _healthy;  // records if stack started properly.
 104
 105   static bool initialize_tcpip();
 106     // starts up the socket mechanisms.  true is returned on success.  if
 107     // true is returned, each call to initialize must be paired with a call
 108     // to deinitialize.
 109
 110   static void deinitialize_tcpip();
 111     // shuts down the socket mechanisms.
 112 };
 113
 114 //////////////
 115
 116 //! Defines our communication related outcome values.
 117
 118 class communication_commons
 119 {
 120 public:
 121   enum outcomes {
 122     DEFINE_API_OUTCOME(NO_CONNECTION, -27, "The connection was dropped or "
 123         "could not be made"),
 124     DEFINE_API_OUTCOME(NO_SERVER, -28, "The server is not responding to "
 125         "requests"),
 126     DEFINE_API_OUTCOME(NO_ANSWER, -29, "The server does not seem to be "
 127         "listening for connections"),
 128     DEFINE_API_OUTCOME(SHUTDOWN, -30, "The object has been shut down or was "
 129         "never started up"),
 130     DEFINE_API_OUTCOME(ALREADY_SETUP, -31, "The object has already been setup"),
 131     DEFINE_API_OUTCOME(MEDIUM_ERROR, -32, "The communications medium is in an "
 132         "unusable state currently"),
 133     DEFINE_API_OUTCOME(BAD_MODE, -33, "The transport cannot operate in the "
 134         "mode specified"),
 135     DEFINE_API_OUTCOME(ALREADY_CONNECTED, -34, "This object is already "
 136         "connected"),
 137     DEFINE_API_OUTCOME(WRONG_ENTITY, -35, "This is the wrong entity type for "
 138          "the request"),
 139     DEFINE_API_OUTCOME(IPC_ERROR, -36, "An error has occurred in interprocess "
 140          "communication"),
 141     DEFINE_API_OUTCOME(TOO_NOISY, -37, "The communications medium is currently "
 142          "too noisy to be used"),
 143     DEFINE_API_OUTCOME(COMM_ERROR, -38, "There was an unspecified "
 144          "communication error")
 145   };
 146
 147   static const char *outcome_name(const basis::outcome &to_name);
 148     // returns a string representation of the outcome "to_name" if it's a
 149     // member of the communication_commons::outcomes enum.
 150 };
 151
 152 } //namespace.
 153
 154 #endif
 155