proton  0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
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 <stddef.h>
28 #include <sys/types.h>
29 
30 #ifdef __cplusplus
31 extern "C" {
32 #endif
33 
34 /** @file
35  * Session API for the proton Engine.
36  *
37  * @defgroup session Session
38  * @ingroup engine
39  * @{
40  */
41 
42 /**
43  * Factory for creating a new session on a given connection object.
44  *
45  * Creates a new session object and adds it to the set of sessions
46  * maintained by the connection object.
47  *
48  * @param[in] connection the connection object
49  * @return a pointer to the new session
50  */
52 
53 /**
54  * Free a session object.
55  *
56  * When a session object is freed, all ::pn_link_t, and
57  * ::pn_delivery_t objects associated with the session are also
58  * freed.
59  *
60  * @param[in] session a session object to free (or NULL)
61  */
63 
64 /**
65  * Get the application context that is associated with a session
66  * object.
67  *
68  * The application context for a session may be set using
69  * ::pn_session_set_context.
70  *
71  * @param[in] session the session whose context is to be returned.
72  * @return the application context for the session object
73  */
75 
76 /**
77  * Set a new application context for a session object.
78  *
79  * The application context for a session object may be retrieved
80  * using ::pn_session_get_context.
81  *
82  * @param[in] session the session object
83  * @param[in] context the application context
84  */
85 PN_EXTERN void pn_session_set_context(pn_session_t *session, void *context);
86 
87 /**
88  * Get the endpoint state flags for a session.
89  *
90  * @param[in] session the session
91  * @return the session's state flags
92  */
94 
95 /**
96  * Get additional error information associated with the session.
97  *
98  * Whenever a session operation fails (i.e. returns an error code),
99  * additional error details can be obtained using this function. The
100  * error object that is returned may also be used to clear the error
101  * condition.
102  *
103  * The pointer returned by this operation is valid until the
104  * session object is freed.
105  *
106  * @param[in] session the sesion object
107  * @return the session's error object
108  */
110 
111 /**
112  * Get the local condition associated with the session endpoint.
113  *
114  * The ::pn_condition_t object retrieved may be modified prior to
115  * closing the session in order to indicate a particular condition
116  * exists when the session closes. This is normally used to
117  * communicate error conditions to the remote peer, however it may
118  * also be used in non error cases. See ::pn_condition_t for more
119  * details.
120  *
121  * The pointer returned by this operation is valid until the session
122  * object is freed.
123  *
124  * @param[in] session the session object
125  * @return the session's local condition object
126  */
128 
129 /**
130  * Get the remote condition associated with the session endpoint.
131  *
132  * The ::pn_condition_t object retrieved may be examined in order to
133  * determine whether the remote peer was indicating some sort of
134  * exceptional condition when the remote session endpoint was
135  * closed. The ::pn_condition_t object returned may not be modified.
136  *
137  * The pointer returned by this operation is valid until the
138  * session object is freed.
139  *
140  * @param[in] session the session object
141  * @return the session's remote condition object
142  */
144 
145 /**
146  * Get the parent connection for a session object.
147  *
148  * This operation retrieves the parent pn_connection_t object that
149  * contains the given pn_session_t object.
150  *
151  * @param[in] session the session object
152  * @return the parent connection object
153  */
155 
156 /**
157  * Open a session.
158  *
159  * Once this operation has completed, the PN_LOCAL_ACTIVE state flag
160  * will be set.
161  *
162  * @param[in] session a session object
163  */
164 PN_EXTERN void pn_session_open(pn_session_t *session);
165 
166 /**
167  * Close a session.
168  *
169  * Once this operation has completed, the PN_LOCAL_CLOSED state flag
170  * will be set. This may be called without calling
171  * ::pn_session_open, in this case it is equivalent to calling
172  * ::pn_session_open followed by ::pn_session_close.
173  *
174  * @param[in] session a session object
175  */
177 
178 /**
179  * Get the incoming capacity of the session measured in bytes.
180  *
181  * The incoming capacity of a session determines how much incoming
182  * message data the session will buffer. Note that if this value is
183  * less than the negotiated frame size of the transport, it will be
184  * rounded up to one full frame.
185  *
186  * @param[in] session the session object
187  * @return the incoming capacity of the session in bytes
188  */
190 
191 /**
192  * Set the incoming capacity for a session object.
193  *
194  * The incoming capacity of a session determines how much incoming
195  * message data the session will buffer. Note that if this value is
196  * less than the negotiated frame size of the transport, it will be
197  * rounded up to one full frame.
198  *
199  * @param[in] session the session object
200  * @param[in] capacity the incoming capacity for the session
201  */
202 PN_EXTERN void pn_session_set_incoming_capacity(pn_session_t *session, size_t capacity);
203 
204 /**
205  * Get the number of outgoing bytes currently buffered by a session.
206  *
207  * @param[in] session a session object
208  * @return the number of outgoing bytes currently buffered
209  */
211 
212 /**
213  * Get the number of incoming bytes currently buffered by a session.
214  *
215  * @param[in] session a session object
216  * @return the number of incoming bytes currently buffered
217  */
219 
220 /**
221  * Retrieve the first session from a given connection that matches the
222  * specified state mask.
223  *
224  * Examines the state of each session owned by the connection, and
225  * returns the first session that matches the given state mask. If
226  * state contains both local and remote flags, then an exact match
227  * against those flags is performed. If state contains only local or
228  * only remote flags, then a match occurs if any of the local or
229  * remote flags are set respectively.
230  *
231  * @param[in] connection to be searched for matching sessions
232  * @param[in] state mask to match
233  * @return the first session owned by the connection that matches the
234  * mask, else NULL if no sessions match
235  */
237 
238 /**
239  * Retrieve the next session from a given connection that matches the
240  * specified state mask.
241  *
242  * When used with ::pn_session_head, application can access all
243  * sessions on the connection that match the given state. See
244  * ::pn_session_head for description of match behavior.
245  *
246  * @param[in] session the previous session obtained from
247  * ::pn_session_head or ::pn_session_next
248  * @param[in] state mask to match.
249  * @return the next session owned by the connection that matches the
250  * mask, else NULL if no sessions match
251  */
253 
254 /** @}
255  */
256 
257 #ifdef __cplusplus
258 }
259 #endif
260 
261 #endif /* session.h */