Merge branch 'release-2.140.131' into dev
[feisty_meow.git] / 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