00001 #ifndef PROTON_SESSION_H 00002 #define PROTON_SESSION_H 1 00003 00004 /* 00005 * 00006 * Licensed to the Apache Software Foundation (ASF) under one 00007 * or more contributor license agreements. See the NOTICE file 00008 * distributed with this work for additional information 00009 * regarding copyright ownership. The ASF licenses this file 00010 * to you under the Apache License, Version 2.0 (the 00011 * "License"); you may not use this file except in compliance 00012 * with the License. You may obtain a copy of the License at 00013 * 00014 * http://www.apache.org/licenses/LICENSE-2.0 00015 * 00016 * Unless required by applicable law or agreed to in writing, 00017 * software distributed under the License is distributed on an 00018 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 00019 * KIND, either express or implied. See the License for the 00020 * specific language governing permissions and limitations 00021 * under the License. 00022 * 00023 */ 00024 00025 #include <proton/import_export.h> 00026 #include <proton/type_compat.h> 00027 #include <proton/types.h> 00028 #include <proton/object.h> 00029 #include <proton/error.h> 00030 #include <proton/condition.h> 00031 #include <stddef.h> 00032 00033 #ifdef __cplusplus 00034 extern "C" { 00035 #endif 00036 00037 /** @file 00038 * Session API for the proton Engine. 00039 * 00040 * @defgroup session Session 00041 * @ingroup engine 00042 * @{ 00043 */ 00044 00045 /** 00046 * Factory for creating a new session on a given connection object. 00047 * 00048 * Creates a new session object and adds it to the set of sessions 00049 * maintained by the connection object. 00050 * 00051 * @param[in] connection the connection object 00052 * @return a pointer to the new session 00053 */ 00054 PN_EXTERN pn_session_t *pn_session(pn_connection_t *connection); 00055 00056 /** 00057 * Free a session object. 00058 * 00059 * When a session is freed it will no longer be retained by the 00060 * connection once any internal references to the session are no 00061 * longer needed. Freeing a session will free all links on that 00062 * session and settle any deliveries on those links. 00063 * 00064 * @param[in] session a session object to free (or NULL) 00065 */ 00066 PN_EXTERN void pn_session_free(pn_session_t *session); 00067 00068 /** 00069 * @deprecated 00070 * Get the application context that is associated with a session 00071 * object. 00072 * 00073 * The application context for a session may be set using 00074 * ::pn_session_set_context. 00075 * 00076 * @param[in] session the session whose context is to be returned. 00077 * @return the application context for the session object 00078 */ 00079 PN_EXTERN void *pn_session_get_context(pn_session_t *session); 00080 00081 /** 00082 * @deprecated 00083 * Set a new application context for a session object. 00084 * 00085 * The application context for a session object may be retrieved 00086 * using ::pn_session_get_context. 00087 * 00088 * @param[in] session the session object 00089 * @param[in] context the application context 00090 */ 00091 PN_EXTERN void pn_session_set_context(pn_session_t *session, void *context); 00092 00093 /** 00094 * Get the attachments that are associated with a session object. 00095 * 00096 * @param[in] session the session whose attachments are to be returned. 00097 * @return the attachments for the session object 00098 */ 00099 PN_EXTERN pn_record_t *pn_session_attachments(pn_session_t *session); 00100 00101 /** 00102 * Get the endpoint state flags for a session. 00103 * 00104 * @param[in] session the session 00105 * @return the session's state flags 00106 */ 00107 PN_EXTERN pn_state_t pn_session_state(pn_session_t *session); 00108 00109 /** 00110 * Get additional error information associated with the session. 00111 * 00112 * Whenever a session operation fails (i.e. returns an error code), 00113 * additional error details can be obtained using this function. The 00114 * error object that is returned may also be used to clear the error 00115 * condition. 00116 * 00117 * The pointer returned by this operation is valid until the 00118 * session object is freed. 00119 * 00120 * @param[in] session the sesion object 00121 * @return the session's error object 00122 */ 00123 PN_EXTERN pn_error_t *pn_session_error(pn_session_t *session); 00124 00125 /** 00126 * Get the local condition associated with the session endpoint. 00127 * 00128 * The ::pn_condition_t object retrieved may be modified prior to 00129 * closing the session in order to indicate a particular condition 00130 * exists when the session closes. This is normally used to 00131 * communicate error conditions to the remote peer, however it may 00132 * also be used in non error cases. See ::pn_condition_t for more 00133 * details. 00134 * 00135 * The pointer returned by this operation is valid until the session 00136 * object is freed. 00137 * 00138 * @param[in] session the session object 00139 * @return the session's local condition object 00140 */ 00141 PN_EXTERN pn_condition_t *pn_session_condition(pn_session_t *session); 00142 00143 /** 00144 * Get the remote condition associated with the session endpoint. 00145 * 00146 * The ::pn_condition_t object retrieved may be examined in order to 00147 * determine whether the remote peer was indicating some sort of 00148 * exceptional condition when the remote session endpoint was 00149 * closed. The ::pn_condition_t object returned may not be modified. 00150 * 00151 * The pointer returned by this operation is valid until the 00152 * session object is freed. 00153 * 00154 * @param[in] session the session object 00155 * @return the session's remote condition object 00156 */ 00157 PN_EXTERN pn_condition_t *pn_session_remote_condition(pn_session_t *session); 00158 00159 /** 00160 * Get the parent connection for a session object. 00161 * 00162 * This operation retrieves the parent pn_connection_t object that 00163 * contains the given pn_session_t object. 00164 * 00165 * @param[in] session the session object 00166 * @return the parent connection object 00167 */ 00168 PN_EXTERN pn_connection_t *pn_session_connection(pn_session_t *session); 00169 00170 /** 00171 * Open a session. 00172 * 00173 * Once this operation has completed, the PN_LOCAL_ACTIVE state flag 00174 * will be set. 00175 * 00176 * @param[in] session a session object 00177 */ 00178 PN_EXTERN void pn_session_open(pn_session_t *session); 00179 00180 /** 00181 * Close a session. 00182 * 00183 * Once this operation has completed, the PN_LOCAL_CLOSED state flag 00184 * will be set. This may be called without calling 00185 * ::pn_session_open, in this case it is equivalent to calling 00186 * ::pn_session_open followed by ::pn_session_close. 00187 * 00188 * @param[in] session a session object 00189 */ 00190 PN_EXTERN void pn_session_close(pn_session_t *session); 00191 00192 /** 00193 * Get the incoming capacity of the session measured in bytes. 00194 * 00195 * The incoming capacity of a session determines how much incoming 00196 * message data the session will buffer. Note that if this value is 00197 * less than the negotiated frame size of the transport, it will be 00198 * rounded up to one full frame. 00199 * 00200 * @param[in] session the session object 00201 * @return the incoming capacity of the session in bytes 00202 */ 00203 PN_EXTERN size_t pn_session_get_incoming_capacity(pn_session_t *session); 00204 00205 /** 00206 * Set the incoming capacity for a session object. 00207 * 00208 * The incoming capacity of a session determines how much incoming 00209 * message data the session will buffer. Note that if this value is 00210 * less than the negotiated frame size of the transport, it will be 00211 * rounded up to one full frame. 00212 * 00213 * @param[in] session the session object 00214 * @param[in] capacity the incoming capacity for the session 00215 */ 00216 PN_EXTERN void pn_session_set_incoming_capacity(pn_session_t *session, size_t capacity); 00217 00218 /** 00219 * Get the outgoing window for a session object. 00220 * 00221 * @param[in] session the session object 00222 * @return the outgoing window for the session 00223 */ 00224 PN_EXTERN size_t pn_session_get_outgoing_window(pn_session_t *session); 00225 00226 /** 00227 * Set the outgoing window for a session object. 00228 * 00229 * @param[in] session the session object 00230 * @param[in] window the outgoing window for the session 00231 */ 00232 PN_EXTERN void pn_session_set_outgoing_window(pn_session_t *session, size_t window); 00233 00234 /** 00235 * Get the number of outgoing bytes currently buffered by a session. 00236 * 00237 * @param[in] session a session object 00238 * @return the number of outgoing bytes currently buffered 00239 */ 00240 PN_EXTERN size_t pn_session_outgoing_bytes(pn_session_t *session); 00241 00242 /** 00243 * Get the number of incoming bytes currently buffered by a session. 00244 * 00245 * @param[in] session a session object 00246 * @return the number of incoming bytes currently buffered 00247 */ 00248 PN_EXTERN size_t pn_session_incoming_bytes(pn_session_t *session); 00249 00250 /** 00251 * Retrieve the first session from a given connection that matches the 00252 * specified state mask. 00253 * 00254 * Examines the state of each session owned by the connection, and 00255 * returns the first session that matches the given state mask. If 00256 * state contains both local and remote flags, then an exact match 00257 * against those flags is performed. If state contains only local or 00258 * only remote flags, then a match occurs if any of the local or 00259 * remote flags are set respectively. 00260 * 00261 * @param[in] connection to be searched for matching sessions 00262 * @param[in] state mask to match 00263 * @return the first session owned by the connection that matches the 00264 * mask, else NULL if no sessions match 00265 */ 00266 PN_EXTERN pn_session_t *pn_session_head(pn_connection_t *connection, pn_state_t state); 00267 00268 /** 00269 * Retrieve the next session from a given connection that matches the 00270 * specified state mask. 00271 * 00272 * When used with ::pn_session_head, application can access all 00273 * sessions on the connection that match the given state. See 00274 * ::pn_session_head for description of match behavior. 00275 * 00276 * @param[in] session the previous session obtained from 00277 * ::pn_session_head or ::pn_session_next 00278 * @param[in] state mask to match. 00279 * @return the next session owned by the connection that matches the 00280 * mask, else NULL if no sessions match 00281 */ 00282 PN_EXTERN pn_session_t *pn_session_next(pn_session_t *session, pn_state_t state); 00283 00284 /** @} 00285 */ 00286 00287 #ifdef __cplusplus 00288 } 00289 #endif 00290 00291 #endif /* session.h */