proton  0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
connection.h
Go to the documentation of this file.
1 #ifndef PROTON_CONNECTION_H
2 #define PROTON_CONNECTION_H 1
3 
4 /*
5  *
6  * Licensed to the Apache Software Foundation (ASF) under one
7  * or more contributor license agreements. See the NOTICE file
8  * distributed with this work for additional information
9  * regarding copyright ownership. The ASF licenses this file
10  * to you under the Apache License, Version 2.0 (the
11  * "License"); you may not use this file except in compliance
12  * with the License. You may obtain a copy of the License at
13  *
14  * http://www.apache.org/licenses/LICENSE-2.0
15  *
16  * Unless required by applicable law or agreed to in writing,
17  * software distributed under the License is distributed on an
18  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
19  * KIND, either express or implied. See the License for the
20  * specific language governing permissions and limitations
21  * under the License.
22  *
23  */
24 
25 #include <proton/import_export.h>
26 #include <proton/type_compat.h>
27 #include <stddef.h>
28 #include <sys/types.h>
29 
30 #ifdef __cplusplus
31 extern "C" {
32 #endif
33 
34 /**
35  * @file
36  *
37  * Connection API for the proton Engine.
38  *
39  * @defgroup connection Connection
40  * @ingroup engine
41  * @{
42  */
43 
44 /**
45  * The local @link pn_state_t endpoint state @endlink is uninitialized.
46  */
47 #define PN_LOCAL_UNINIT (1)
48 /**
49  * The local @link pn_state_t endpoint state @endlink is active.
50  */
51 #define PN_LOCAL_ACTIVE (2)
52 /**
53  * The local @link pn_state_t endpoint state @endlink is closed.
54  */
55 #define PN_LOCAL_CLOSED (4)
56 /**
57  * The remote @link pn_state_t endpoint state @endlink is uninitialized.
58  */
59 #define PN_REMOTE_UNINIT (8)
60 /**
61  * The remote @link pn_state_t endpoint state @endlink is active.
62  */
63 #define PN_REMOTE_ACTIVE (16)
64 /**
65  * The remote @link pn_state_t endpoint state @endlink is closed.
66  */
67 #define PN_REMOTE_CLOSED (32)
68 
69 /**
70  * A mask for values of ::pn_state_t that preserves only the local
71  * bits of an endpoint's state.
72  */
73 #define PN_LOCAL_MASK (PN_LOCAL_UNINIT | PN_LOCAL_ACTIVE | PN_LOCAL_CLOSED)
74 
75 /**
76  * A mask for values of ::pn_state_t that preserves only the remote
77  * bits of an endpoint's state.
78  */
79 #define PN_REMOTE_MASK (PN_REMOTE_UNINIT | PN_REMOTE_ACTIVE | PN_REMOTE_CLOSED)
80 
81 /**
82  * Factory to construct a new Connection.
83  *
84  * @return pointer to a new connection object.
85  */
87 
88 /**
89  * Free a connection object.
90  *
91  * When a connection object is freed, all ::pn_session_t, ::pn_link_t,
92  * and ::pn_delivery_t objects associated with the connection are also
93  * freed.
94  *
95  * @param[in] connection the connection object to free (or NULL)
96  */
98 
99 /**
100  * Get additional error information associated with the connection.
101  *
102  * Whenever a connection operation fails (i.e. returns an error code),
103  * additional error details can be obtained using this function. The
104  * error object that is returned may also be used to clear the error
105  * condition.
106  *
107  * The pointer returned by this operation is valid until the
108  * connection object is freed.
109  *
110  * @param[in] connection the connection object
111  * @return the connection's error object
112  */
114 
115 /**
116  * Associate a connection object with an event collector.
117  *
118  * By associating a connection object with an event collector, key
119  * changes in endpoint state are reported to the collector via
120  * ::pn_event_t objects that can be inspected and processed. See
121  * ::pn_event_t for more details on the kinds of events.
122  *
123  * Note that by registering a collector, the user is requesting that
124  * an indefinite number of events be queued up on his behalf. This
125  * means that unless the application eventually processes these
126  * events, the storage requirements for keeping them will grow without
127  * bound. In other words, don't register a collector with a connection
128  * if you never intend to process any of the events.
129  *
130  * @param[in] connection the connection object
131  * @param[in] collector the event collector
132  */
133 PN_EXTERN void pn_connection_collect(pn_connection_t *connection, pn_collector_t *collector);
134 
135 /**
136  * Get the application context that is associated with a connection
137  * object.
138  *
139  * The application context for a connection may be set using
140  * ::pn_connection_set_context.
141  *
142  * @param[in] connection the connection whose context is to be returned.
143  * @return the application context for the connection object
144  */
146 
147 /**
148  * Set a new application context for a connection object.
149  *
150  * The application context for a connection object may be retrieved
151  * using ::pn_connection_get_context.
152  *
153  * @param[in] connection the connection object
154  * @param[in] context the application context
155  */
156 PN_EXTERN void pn_connection_set_context(pn_connection_t *connection, void *context);
157 
158 /**
159  * Get the endpoint state flags for a connection.
160  *
161  * @param[in] connection the connection
162  * @return the connection's state flags
163  */
165 
166 /**
167  * Open a connection.
168  *
169  * Once this operation has completed, the PN_LOCAL_ACTIVE state flag
170  * will be set.
171  *
172  * @param[in] connection a connection object
173  */
175 
176 /**
177  * Close a connection.
178  *
179  * Once this operation has completed, the PN_LOCAL_CLOSED state flag
180  * will be set. This may be called without calling
181  * ::pn_connection_open, in this case it is equivalent to calling
182  * ::pn_connection_open followed by ::pn_connection_close.
183  *
184  * @param[in] connection a connection object
185  */
187 
188 /**
189  * Reset a connection object back to the uninitialized state.
190  *
191  * Note that this does *not* remove any contained ::pn_session_t,
192  * ::pn_link_t, and ::pn_delivery_t objects.
193  *
194  * @param[in] connection a connection object
195  */
197 
198 /**
199  * Get the local condition associated with the connection endpoint.
200  *
201  * The ::pn_condition_t object retrieved may be modified prior to
202  * closing the connection in order to indicate a particular condition
203  * exists when the connection closes. This is normally used to
204  * communicate error conditions to the remote peer, however it may
205  * also be used in non error cases such as redirects. See
206  * ::pn_condition_t for more details.
207  *
208  * The pointer returned by this operation is valid until the
209  * connection object is freed.
210  *
211  * @param[in] connection the connection object
212  * @return the connection's local condition object
213  */
215 
216 /**
217  * Get the remote condition associated with the connection endpoint.
218  *
219  * The ::pn_condition_t object retrieved may be examined in order to
220  * determine whether the remote peer was indicating some sort of
221  * exceptional condition when the remote connection endpoint was
222  * closed. The ::pn_condition_t object returned may not be modified.
223  *
224  * The pointer returned by this operation is valid until the
225  * connection object is freed.
226  *
227  * @param[in] connection the connection object
228  * @return the connection's remote condition object
229  */
231 
232 /**
233  * Get the AMQP Container name advertised by a connection object.
234  *
235  * The pointer returned by this operation is valid until
236  * ::pn_connection_set_container is called, or until the connection
237  * object is freed, whichever happens sooner.
238  *
239  * @param[in] connection the connection object
240  * @return a pointer to the container name
241  */
242 PN_EXTERN const char *pn_connection_get_container(pn_connection_t *connection);
243 
244 /**
245  * Set the AMQP Container name advertised by a connection object.
246  *
247  * @param[in] connection the connection object
248  * @param[in] container the container name
249  */
250 PN_EXTERN void pn_connection_set_container(pn_connection_t *connection, const char *container);
251 
252 /**
253  * Get the value of the AMQP Hostname used by a connection object.
254  *
255  * The pointer returned by this operation is valid until
256  * ::pn_connection_set_hostname is called, or until the connection
257  * object is freed, whichever happens sooner.
258  *
259  * @param[in] connection the connection object
260  * @return a pointer to the hostname
261  */
262 PN_EXTERN const char *pn_connection_get_hostname(pn_connection_t *connection);
263 
264 /**
265  * Set the value of the AMQP Hostname used by a connection object.
266  *
267  * @param[in] connection the connection object
268  * @param[in] hostname the hostname
269  */
270 PN_EXTERN void pn_connection_set_hostname(pn_connection_t *connection, const char *hostname);
271 
272 /**
273  * Get the AMQP Container name advertised by the remote connection
274  * endpoint.
275  *
276  * This will return NULL until the ::PN_REMOTE_ACTIVE state is
277  * reached. See ::pn_state_t for more details on endpoint state.
278  *
279  * Any non null pointer returned by this operation will be valid until
280  * the connection object is unbound from a transport or freed,
281  * whichever happens sooner.
282  *
283  * @param[in] connection the connection object
284  * @return a pointer to the remote container name
285  */
287 
288 /**
289  * Get the AMQP Hostname set by the remote connection endpoint.
290  *
291  * This will return NULL until the ::PN_REMOTE_ACTIVE state is
292  * reached. See ::pn_state_t for more details on endpoint state.
293  *
294  * Any non null pointer returned by this operation will be valid until
295  * the connection object is unbound from a transport or freed,
296  * whichever happens sooner.
297  *
298  * @param[in] connection the connection object
299  * @return a pointer to the remote hostname
300  */
302 
303 /**
304  * Access/modify the AMQP offered capabilities data for a connection
305  * object.
306  *
307  * This operation will return a pointer to a ::pn_data_t object that
308  * is valid until the connection object is freed. Any data contained
309  * by the ::pn_data_t object will be sent as the offered capabilites
310  * for the parent connection object. Note that this MUST take the form
311  * of an array of symbols to be valid.
312  *
313  * The ::pn_data_t pointer returned is valid until the connection
314  * object is freed.
315  *
316  * @param[in] connection the connection object
317  * @return a pointer to a pn_data_t representing the offered capabilities
318  */
320 
321 /**
322  * Access/modify the AMQP desired capabilities data for a connection
323  * object.
324  *
325  * This operation will return a pointer to a ::pn_data_t object that
326  * is valid until the connection object is freed. Any data contained
327  * by the ::pn_data_t object will be sent as the desired capabilites
328  * for the parent connection object. Note that this MUST take the form
329  * of an array of symbols to be valid.
330  *
331  * The ::pn_data_t pointer returned is valid until the connection
332  * object is freed.
333  *
334  * @param[in] connection the connection object
335  * @return a pointer to a pn_data_t representing the desired capabilities
336  */
338 
339 /**
340  * Access/modify the AMQP properties data for a connection object.
341  *
342  * This operation will return a pointer to a ::pn_data_t object that
343  * is valid until the connection object is freed. Any data contained
344  * by the ::pn_data_t object will be sent as the AMQP properties for
345  * the parent connection object. Note that this MUST take the form of
346  * a symbol keyed map to be valid.
347  *
348  * The ::pn_data_t pointer returned is valid until the connection
349  * object is freed.
350  *
351  * @param[in] connection the connection object
352  * @return a pointer to a pn_data_t representing the connection properties
353  */
355 
356 /**
357  * Access the AMQP offered capabilites supplied by the remote
358  * connection endpoint.
359  *
360  * This operation will return a pointer to a ::pn_data_t object that
361  * is valid until the connection object is freed. This data object
362  * will be empty until the remote connection is opened as indicated by
363  * the ::PN_REMOTE_ACTIVE flag.
364  *
365  * @param[in] connection the connection object
366  * @return the remote offered capabilities
367  */
369 
370 /**
371  * Access the AMQP desired capabilites supplied by the remote
372  * connection endpoint.
373  *
374  * This operation will return a pointer to a ::pn_data_t object that
375  * is valid until the connection object is freed. This data object
376  * will be empty until the remote connection is opened as indicated by
377  * the ::PN_REMOTE_ACTIVE flag.
378  *
379  * @param[in] connection the connection object
380  * @return the remote desired capabilities
381  */
383 
384 /**
385  * Access the AMQP connection properties supplied by the remote
386  * connection endpoint.
387  *
388  * This operation will return a pointer to a ::pn_data_t object that
389  * is valid until the connection object is freed. This data object
390  * will be empty until the remote connection is opened as indicated by
391  * the ::PN_REMOTE_ACTIVE flag.
392  *
393  * @param[in] connection the connection object
394  * @return the remote connection properties
395  */
397 
398 /**
399  * Get the transport bound to a connection object.
400  *
401  * If the connection is unbound, then this operation will return NULL.
402  *
403  * @param[in] connection the connection object
404  * @return the transport bound to a connection, or NULL if the
405  * connection is unbound
406  */
408 
409 /** @}
410  */
411 
412 #ifdef __cplusplus
413 }
414 #endif
415 
416 #endif /* connection.h */