proton  0
session.h
Go to the documentation of this file.
1 #ifndef PROTON_SESSION_H
2 #define PROTON_SESSION_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 <proton/types.h>
28 #include <proton/object.h>
29 #include <proton/error.h>
30 #include <proton/condition.h>
31 #include <stddef.h>
32 
33 #ifdef __cplusplus
34 extern "C" {
35 #endif
36 
37 /** @file
38  * Session API for the proton Engine.
39  *
40  * @defgroup session Session
41  * @ingroup engine
42  * @{
43  */
44 
45 /**
46  * Factory for creating a new session on a given connection object.
47  *
48  * Creates a new session object and adds it to the set of sessions
49  * maintained by the connection object.
50  *
51  * @param[in] connection the connection object
52  * @return a pointer to the new session
53  */
55 
56 /**
57  * Free a session object.
58  *
59  * When a session is freed it will no longer be retained by the
60  * connection once any internal references to the session are no
61  * longer needed. Freeing a session will free all links on that
62  * session and settle any deliveries on those links.
63  *
64  * @param[in] session a session object to free (or NULL)
65  */
67 
68 /**
69  * @deprecated
70  * Get the application context that is associated with a session
71  * object.
72  *
73  * The application context for a session may be set using
74  * ::pn_session_set_context.
75  *
76  * @param[in] session the session whose context is to be returned.
77  * @return the application context for the session object
78  */
80 
81 /**
82  * @deprecated
83  * Set a new application context for a session object.
84  *
85  * The application context for a session object may be retrieved
86  * using ::pn_session_get_context.
87  *
88  * @param[in] session the session object
89  * @param[in] context the application context
90  */
91 PN_EXTERN void pn_session_set_context(pn_session_t *session, void *context);
92 
93 /**
94  * Get the attachments that are associated with a session object.
95  *
96  * @param[in] session the session whose attachments are to be returned.
97  * @return the attachments for the session object
98  */
100 
101 /**
102  * Get the endpoint state flags for a session.
103  *
104  * @param[in] session the session
105  * @return the session's state flags
106  */
108 
109 /**
110  * Get additional error information associated with the session.
111  *
112  * Whenever a session operation fails (i.e. returns an error code),
113  * additional error details can be obtained using this function. The
114  * error object that is returned may also be used to clear the error
115  * condition.
116  *
117  * The pointer returned by this operation is valid until the
118  * session object is freed.
119  *
120  * @param[in] session the sesion object
121  * @return the session's error object
122  */
124 
125 /**
126  * Get the local condition associated with the session endpoint.
127  *
128  * The ::pn_condition_t object retrieved may be modified prior to
129  * closing the session in order to indicate a particular condition
130  * exists when the session closes. This is normally used to
131  * communicate error conditions to the remote peer, however it may
132  * also be used in non error cases. See ::pn_condition_t for more
133  * details.
134  *
135  * The pointer returned by this operation is valid until the session
136  * object is freed.
137  *
138  * @param[in] session the session object
139  * @return the session's local condition object
140  */
142 
143 /**
144  * Get the remote condition associated with the session endpoint.
145  *
146  * The ::pn_condition_t object retrieved may be examined in order to
147  * determine whether the remote peer was indicating some sort of
148  * exceptional condition when the remote session endpoint was
149  * closed. The ::pn_condition_t object returned may not be modified.
150  *
151  * The pointer returned by this operation is valid until the
152  * session object is freed.
153  *
154  * @param[in] session the session object
155  * @return the session's remote condition object
156  */
158 
159 /**
160  * Get the parent connection for a session object.
161  *
162  * This operation retrieves the parent pn_connection_t object that
163  * contains the given pn_session_t object.
164  *
165  * @param[in] session the session object
166  * @return the parent connection object
167  */
169 
170 /**
171  * Open a session.
172  *
173  * Once this operation has completed, the PN_LOCAL_ACTIVE state flag
174  * will be set.
175  *
176  * @param[in] session a session object
177  */
178 PN_EXTERN void pn_session_open(pn_session_t *session);
179 
180 /**
181  * Close a session.
182  *
183  * Once this operation has completed, the PN_LOCAL_CLOSED state flag
184  * will be set. This may be called without calling
185  * ::pn_session_open, in this case it is equivalent to calling
186  * ::pn_session_open followed by ::pn_session_close.
187  *
188  * @param[in] session a session object
189  */
191 
192 /**
193  * Get the incoming capacity of the session measured in bytes.
194  *
195  * The incoming capacity of a session determines how much incoming
196  * message data the session will buffer. Note that if this value is
197  * less than the negotiated frame size of the transport, it will be
198  * rounded up to one full frame.
199  *
200  * @param[in] session the session object
201  * @return the incoming capacity of the session in bytes
202  */
204 
205 /**
206  * Set the incoming capacity for a session object.
207  *
208  * The incoming capacity of a session determines how much incoming
209  * message data the session will buffer. Note that if this value is
210  * less than the negotiated frame size of the transport, it will be
211  * rounded up to one full frame.
212  *
213  * @param[in] session the session object
214  * @param[in] capacity the incoming capacity for the session
215  */
216 PN_EXTERN void pn_session_set_incoming_capacity(pn_session_t *session, size_t capacity);
217 
218 /**
219  * Get the outgoing window for a session object.
220  *
221  * @param[in] session the session object
222  * @return the outgoing window for the session
223  */
225 
226 /**
227  * Set the outgoing window for a session object.
228  *
229  * @param[in] session the session object
230  * @param[in] window the outgoing window for the session
231  */
232 PN_EXTERN void pn_session_set_outgoing_window(pn_session_t *session, size_t window);
233 
234 /**
235  * Get the number of outgoing bytes currently buffered by a session.
236  *
237  * @param[in] session a session object
238  * @return the number of outgoing bytes currently buffered
239  */
241 
242 /**
243  * Get the number of incoming bytes currently buffered by a session.
244  *
245  * @param[in] session a session object
246  * @return the number of incoming bytes currently buffered
247  */
249 
250 /**
251  * Retrieve the first session from a given connection that matches the
252  * specified state mask.
253  *
254  * Examines the state of each session owned by the connection, and
255  * returns the first session that matches the given state mask. If
256  * state contains both local and remote flags, then an exact match
257  * against those flags is performed. If state contains only local or
258  * only remote flags, then a match occurs if any of the local or
259  * remote flags are set respectively.
260  *
261  * @param[in] connection to be searched for matching sessions
262  * @param[in] state mask to match
263  * @return the first session owned by the connection that matches the
264  * mask, else NULL if no sessions match
265  */
267 
268 /**
269  * Retrieve the next session from a given connection that matches the
270  * specified state mask.
271  *
272  * When used with ::pn_session_head, application can access all
273  * sessions on the connection that match the given state. See
274  * ::pn_session_head for description of match behavior.
275  *
276  * @param[in] session the previous session obtained from
277  * ::pn_session_head or ::pn_session_next
278  * @param[in] state mask to match.
279  * @return the next session owned by the connection that matches the
280  * mask, else NULL if no sessions match
281  */
283 
284 /** @}
285  */
286 
287 #ifdef __cplusplus
288 }
289 #endif
290 
291 #endif /* session.h */
PN_EXTERN pn_session_t * pn_session_next(pn_session_t *session, pn_state_t state)
Retrieve the next session from a given connection that matches the specified state mask...
PN_EXTERN size_t pn_session_get_incoming_capacity(pn_session_t *session)
Get the incoming capacity of the session measured in bytes.
PN_EXTERN void pn_session_close(pn_session_t *session)
Close a session.
PN_EXTERN pn_condition_t * pn_session_condition(pn_session_t *session)
Get the local condition associated with the session endpoint.
PN_EXTERN void pn_session_open(pn_session_t *session)
Open a session.
struct pn_connection_t pn_connection_t
An AMQP Connection object.
Definition: types.h:111
PN_EXTERN pn_connection_t * pn_session_connection(pn_session_t *session)
Get the parent connection for a session object.
PN_EXTERN void pn_session_free(pn_session_t *session)
Free a session object.
struct pn_condition_t pn_condition_t
An AMQP Condition object.
Definition: condition.h:64
struct pn_error_t pn_error_t
Definition: error.h:32
PN_EXTERN pn_session_t * pn_session(pn_connection_t *connection)
Factory for creating a new session on a given connection object.
PN_EXTERN size_t pn_session_get_outgoing_window(pn_session_t *session)
Get the outgoing window for a session object.
PN_EXTERN void pn_session_set_incoming_capacity(pn_session_t *session, size_t capacity)
Set the incoming capacity for a session object.
PN_EXTERN pn_record_t * pn_session_attachments(pn_session_t *session)
Get the attachments that are associated with a session object.
The Condition API for the proton Engine.
PN_EXTERN size_t pn_session_incoming_bytes(pn_session_t *session)
Get the number of incoming bytes currently buffered by a session.
PN_EXTERN pn_state_t pn_session_state(pn_session_t *session)
Get the endpoint state flags for a session.
PN_EXTERN pn_condition_t * pn_session_remote_condition(pn_session_t *session)
Get the remote condition associated with the session endpoint.
PN_EXTERN pn_session_t * pn_session_head(pn_connection_t *connection, pn_state_t state)
Retrieve the first session from a given connection that matches the specified state mask...
struct pn_record_t pn_record_t
Definition: object.h:46
PN_EXTERN pn_error_t * pn_session_error(pn_session_t *session)
Get additional error information associated with the session.
struct pn_session_t pn_session_t
An AMQP Session object.
Definition: types.h:122
PN_EXTERN void pn_session_set_outgoing_window(pn_session_t *session, size_t window)
Set the outgoing window for a session object.
#define PN_EXTERN
Definition: import_export.h:53
PN_EXTERN size_t pn_session_outgoing_bytes(pn_session_t *session)
Get the number of outgoing bytes currently buffered by a session.
PN_EXTERN void pn_session_set_context(pn_session_t *session, void *context)
PN_EXTERN void * pn_session_get_context(pn_session_t *session)
int pn_state_t
Holds the state flags for an AMQP endpoint.
Definition: types.h:96