Add compilation guard; prepare for #inclusion in C++
[OpenSRF.git] / include / opensrf / osrf_transgroup.h
1 #ifndef OSRF_TRANSGROUP_H
2 #define OSRF_TRANSGROUP_H
3
4 #include <opensrf/transport_client.h>
5 #include <opensrf/transport_message.h>
6 #include <opensrf/osrf_list.h>
7 #include <opensrf/osrf_hash.h>
8 #include <opensrf/osrfConfig.h>
9 #include <opensrf/utils.h>
10 #include <time.h>
11
12 #ifdef __cplusplus
13 extern "C" {
14 #endif
15
16 /**
17   Maintains a set of transport clients 
18   */
19
20 struct __osrfTransportGroupStruct {
21         osrfHash* nodes;                                                /* our hash of nodes keyed by domain */
22         osrfHashIterator* itr;                          /* points to the next node in the list */
23 };
24 typedef struct __osrfTransportGroupStruct osrfTransportGroup;
25
26
27 struct __osrfTransportGroupNode {
28         transport_client* connection;           /* our connection to the network */
29         char* domain;                                                   /* the domain we're connected to */
30         char* username;                                         /* username used to connect to the group of servers */
31         char* password;                                         /* password used to connect to the group of servers */
32         char* resource;                                         /* the login resource */
33         int port;                                                               /* port used to connect to the group of servers */
34
35         int active;                                                             /* true if we're able to send data on this connection */
36         time_t lastsent;                                                /* the last time we sent a message */
37 };
38 typedef struct __osrfTransportGroupNode osrfTransportGroupNode;
39
40
41 /**
42   Creates a new group node
43   @param domain The domain we're connecting to
44   @param port The port to connect on
45   @param username The login name
46   @param password The login password
47   @param resource The login resource
48   @return A new transport group node
49   */
50 osrfTransportGroupNode* osrfNewTransportGroupNode( 
51                 char* domain, int port, char* username, char* password, char* resource );
52
53
54 /**
55   Allocates and initializes a new transport group.
56   The first node in the array is the default node for client connections.
57   @param nodes The nodes in the group.
58   */
59 osrfTransportGroup* osrfNewTransportGroup( osrfTransportGroupNode* nodes[], int count );
60
61 /**
62   Attempts to connect all of the nodes in this group.
63   @param grp The transport group
64   @return The number of nodes successfully connected
65   */
66 int osrfTransportGroupConnectAll( osrfTransportGroup* grp );
67
68 void osrfTransportGroupDisconnectAll( osrfTransportGroup* grp );
69
70
71 /**
72   Sends a transport message by going to the next domain in the set.
73   if we have a connection for the recipient domain, then we consider it to be
74   a 'local' message.  Local messages have their recipient domains re-written to
75   match the domain of the next server in the set and they are sent directly to 
76   that server.  If we do not have a connection for the recipient domain, it is 
77   considered a 'remote' message and the message is sent directly (unchanged)
78   to the next connection in the set.
79
80   @param grp The transport group
81   @param msg The message to send 
82   @return 0 on normal successful send.  
83   Returns -1 if the message cannot be sent.  
84   */
85 int osrfTransportGroupSend( osrfTransportGroup* grp, transport_message* msg );
86
87 /**
88   Sends the message to the exact recipient.  No failover is attempted.
89   @return 0 on success, -1 on error.
90   */
91 int osrfTransportGroupSendMatch( osrfTransportGroup* grp, transport_message* msg );
92
93
94 int _osrfTGServerSend( osrfTransportGroup* grp, char* domain, transport_message* msg );
95 int _osrfTGClientSend( osrfTransportGroup* grp, char* domain, transport_message* msg );
96
97 /**
98   Waits on all connections for inbound data.
99   @param grp The transport group
100   @param timeout How long to wait for data.  0 means check for data
101   but don't wait, a negative number means to wait indefinitely
102   @return The received message or NULL if the timeout occurred before a 
103   message was received 
104  */
105 transport_message* osrfTransportGroupRecvAll( osrfTransportGroup* grp, int timeout );
106
107 /**
108   Waits for data from a single domain
109   @param grp The transport group
110   @param domain The domain to wait for data on
111   @param timeout see osrfTransportGroupRecvAll
112   */
113 transport_message* osrfTransportGroupRecv( osrfTransportGroup* grp, char* domain, int timeout );
114
115 /**
116   Tells the group that a message to the given domain failed
117   domain did not make it through;
118   @param grp The transport group
119   @param comain The failed domain
120   */
121 void osrfTransportGroupSetInactive( osrfTransportGroup* grp, char* domain );
122
123
124 /**
125   Finds a node in our list of nodes 
126   */
127 osrfTransportGroupNode* __osrfTransportGroupFindNode( osrfTransportGroup* grp, char* domain );
128
129 #ifdef __cplusplus
130 }
131 #endif
132
133 #endif
134