00001 #ifndef PROTON_LINK_H 00002 #define PROTON_LINK_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 <stddef.h> 00028 #include <sys/types.h> 00029 00030 #ifdef __cplusplus 00031 extern "C" { 00032 #endif 00033 00034 /** 00035 * @file 00036 * 00037 * Link API for the proton Engine. 00038 * 00039 * @defgroup link Link 00040 * @ingroup engine 00041 * @{ 00042 */ 00043 00044 /** 00045 * Construct a new sender on a session. 00046 * 00047 * Each sending link between two AMQP containers must be uniquely 00048 * named. Note that this uniqueness cannot be enforced at the API 00049 * level, so some consideration should be taken in choosing link 00050 * names. 00051 * 00052 * @param[in] session the session object 00053 * @param[in] name the name of the link 00054 * @return a newly constructed sender link or NULL on error 00055 */ 00056 PN_EXTERN pn_link_t *pn_sender(pn_session_t *session, const char *name); 00057 00058 /** 00059 * Construct a new receiver on a session. 00060 * 00061 * Each receiving link between two AMQP containers must be uniquely 00062 * named. Note that this uniqueness cannot be enforced at the API 00063 * level, so some consideration should be taken in choosing link 00064 * names. 00065 * 00066 * @param[in] session the session object 00067 * @param[in] name the name of the link 00068 * @return a newly constructed receiver link or NULL on error 00069 */ 00070 PN_EXTERN pn_link_t *pn_receiver(pn_session_t *session, const char *name); 00071 00072 /** 00073 * Free a link object. 00074 * 00075 * When a link object is freed, all ::pn_delivery_t objects associated 00076 * with the session are also freed. 00077 * 00078 * @param[in] link a link object to free (or NULL) 00079 */ 00080 PN_EXTERN void pn_link_free(pn_link_t *link); 00081 00082 /** 00083 * Get the application context that is associated with a link object. 00084 * 00085 * The application context for a link may be set using 00086 * ::pn_link_set_context. 00087 * 00088 * @param[in] link the link whose context is to be returned. 00089 * @return the application context for the link object 00090 */ 00091 PN_EXTERN void *pn_link_get_context(pn_link_t *link); 00092 00093 /** 00094 * Set a new application context for a link object. 00095 * 00096 * The application context for a link object may be retrieved using 00097 * ::pn_link_get_context. 00098 * 00099 * @param[in] link the link object 00100 * @param[in] context the application context 00101 */ 00102 PN_EXTERN void pn_link_set_context(pn_link_t *link, void *context); 00103 00104 /** 00105 * Get the name of a link. 00106 * 00107 * @param[in] link a link object 00108 * @return the name of the link 00109 */ 00110 PN_EXTERN const char *pn_link_name(pn_link_t *link); 00111 00112 /** 00113 * Test if a link is a sender. 00114 * 00115 * @param[in] link a link object 00116 * @return true if and only if the link is a sender 00117 */ 00118 PN_EXTERN bool pn_link_is_sender(pn_link_t *link); 00119 00120 /** 00121 * Test if a link is a receiver. 00122 * 00123 * @param[in] link a link object 00124 * @return true if and only if the link is a receiver 00125 */ 00126 PN_EXTERN bool pn_link_is_receiver(pn_link_t *link); 00127 00128 /** 00129 * Get the endpoint state flags for a link. 00130 * 00131 * @param[in] link the link 00132 * @return the link's state flags 00133 */ 00134 PN_EXTERN pn_state_t pn_link_state(pn_link_t *link); 00135 00136 /** 00137 * Get additional error information associated with the link. 00138 * 00139 * Whenever a link operation fails (i.e. returns an error code), 00140 * additional error details can be obtained using this function. The 00141 * error object that is returned may also be used to clear the error 00142 * condition. 00143 * 00144 * The pointer returned by this operation is valid until the 00145 * link object is freed. 00146 * 00147 * @param[in] link the link object 00148 * @return the link's error object 00149 */ 00150 PN_EXTERN pn_error_t *pn_link_error(pn_link_t *link); 00151 00152 /** 00153 * Get the local condition associated with a link endpoint. 00154 * 00155 * The ::pn_condition_t object retrieved may be modified prior to 00156 * closing a link in order to indicate a particular condition 00157 * exists when the link closes. This is normally used to 00158 * communicate error conditions to the remote peer, however it may 00159 * also be used in non error cases. See ::pn_condition_t for more 00160 * details. 00161 * 00162 * The pointer returned by this operation is valid until the link 00163 * object is freed. 00164 * 00165 * @param[in] link the link object 00166 * @return the link's local condition object 00167 */ 00168 PN_EXTERN pn_condition_t *pn_link_condition(pn_link_t *link); 00169 00170 /** 00171 * Get the remote condition associated with a link endpoint. 00172 * 00173 * The ::pn_condition_t object retrieved may be examined in order to 00174 * determine whether the remote peer was indicating some sort of 00175 * exceptional condition when the remote link endpoint was 00176 * closed. The ::pn_condition_t object returned may not be modified. 00177 * 00178 * The pointer returned by this operation is valid until the 00179 * link object is freed. 00180 * 00181 * @param[in] link the link object 00182 * @return the link's remote condition object 00183 */ 00184 PN_EXTERN pn_condition_t *pn_link_remote_condition(pn_link_t *link); 00185 00186 /** 00187 * Get the parent session for a link object. 00188 * 00189 * This operation retrieves the parent ::pn_session_t object that 00190 * contains the given ::pn_link_t object. 00191 * 00192 * @param[in] link the link object 00193 * @return the parent session object 00194 */ 00195 PN_EXTERN pn_session_t *pn_link_session(pn_link_t *link); 00196 00197 /** 00198 * Retrieve the first link that matches the given state mask. 00199 * 00200 * Examines the state of each link owned by the connection and returns 00201 * the first link that matches the given state mask. If state contains 00202 * both local and remote flags, then an exact match against those 00203 * flags is performed. If state contains only local or only remote 00204 * flags, then a match occurs if any of the local or remote flags are 00205 * set respectively. 00206 * 00207 * @param[in] connection to be searched for matching Links 00208 * @param[in] state mask to match 00209 * @return the first link owned by the connection that matches the 00210 * mask, else NULL if no links match 00211 */ 00212 PN_EXTERN pn_link_t *pn_link_head(pn_connection_t *connection, pn_state_t state); 00213 00214 /** 00215 * Retrieve the next link that matches the given state mask. 00216 * 00217 * When used with pn_link_head, the application can access all links 00218 * on the connection that match the given state. See pn_link_head for 00219 * description of match behavior. 00220 * 00221 * @param[in] link the previous link obtained from pn_link_head or 00222 * pn_link_next 00223 * @param[in] state mask to match 00224 * @return the next session owned by the connection that matches the 00225 * mask, else NULL if no sessions match 00226 */ 00227 PN_EXTERN pn_link_t *pn_link_next(pn_link_t *link, pn_state_t state); 00228 00229 /** 00230 * Open a link. 00231 * 00232 * Once this operation has completed, the PN_LOCAL_ACTIVE state flag 00233 * will be set. 00234 * 00235 * @param[in] link a link object 00236 */ 00237 PN_EXTERN void pn_link_open(pn_link_t *link); 00238 00239 /** 00240 * Close a link. 00241 * 00242 * Once this operation has completed, the PN_LOCAL_CLOSED state flag 00243 * will be set. This may be called without calling 00244 * ::pn_link_open, in this case it is equivalent to calling 00245 * ::pn_link_open followed by ::pn_link_close. 00246 * 00247 * @param[in] link a link object 00248 */ 00249 PN_EXTERN void pn_link_close(pn_link_t *link); 00250 00251 /** 00252 * Access the locally defined source definition for a link. 00253 * 00254 * The pointer returned by this operation is valid until the link 00255 * object is freed. 00256 * 00257 * @param[in] link a link object 00258 * @return a pointer to a source terminus 00259 */ 00260 PN_EXTERN pn_terminus_t *pn_link_source(pn_link_t *link); 00261 00262 /** 00263 * Access the locally defined target definition for a link. 00264 * 00265 * The pointer returned by this operation is valid until the link 00266 * object is freed. 00267 * 00268 * @param[in] link a link object 00269 * @return a pointer to a target terminus 00270 */ 00271 PN_EXTERN pn_terminus_t *pn_link_target(pn_link_t *link); 00272 00273 /** 00274 * Access the remotely defined source definition for a link. 00275 * 00276 * The pointer returned by this operation is valid until the link 00277 * object is freed. The remotely defined terminus will be empty until 00278 * the link is remotely opened as indicated by the PN_REMOTE_ACTIVE 00279 * flag. 00280 * 00281 * @param[in] link a link object 00282 * @return a pointer to the remotely defined source terminus 00283 */ 00284 PN_EXTERN pn_terminus_t *pn_link_remote_source(pn_link_t *link); 00285 00286 /** 00287 * Access the remotely defined target definition for a link. 00288 * 00289 * The pointer returned by this operation is valid until the link 00290 * object is freed. The remotely defined terminus will be empty until 00291 * the link is remotely opened as indicated by the PN_REMOTE_ACTIVE 00292 * flag. 00293 * 00294 * @param[in] link a link object 00295 * @return a pointer to the remotely defined target terminus 00296 */ 00297 PN_EXTERN pn_terminus_t *pn_link_remote_target(pn_link_t *link); 00298 00299 /** 00300 * Get the current delivery for a link. 00301 * 00302 * Each link maintains a sequence of deliveries in the order they were 00303 * created, along with a pointer to the *current* delivery. All 00304 * send/recv operations on a link take place on the *current* 00305 * delivery. If a link has no current delivery, the current delivery 00306 * is automatically initialized to the next delivery created on the 00307 * link. Once initialized, the current delivery remains the same until 00308 * it is changed through use of ::pn_link_advance or until it is 00309 * settled via ::pn_delivery_settle. 00310 * 00311 * @param[in] link a link object 00312 * @return the current delivery for the link, or NULL if there is none 00313 */ 00314 PN_EXTERN pn_delivery_t *pn_link_current(pn_link_t *link); 00315 00316 /** 00317 * Advance the current delivery of a link to the next delivery on the 00318 * link. 00319 * 00320 * For sending links this operation is used to finish sending message 00321 * data for the current outgoing delivery and move on to the next 00322 * outgoing delivery (if any). 00323 * 00324 * For receiving links, this operation is used to finish accessing 00325 * message data from the current incoming delivery and move on to the 00326 * next incoming delivery (if any). 00327 * 00328 * Each link maintains a sequence of deliveries in the order they were 00329 * created, along with a pointer to the *current* delivery. The 00330 * pn_link_advance operation will modify the *current* delivery on the 00331 * link to point to the next delivery in the sequence. If there is no 00332 * next delivery in the sequence, the current delivery will be set to 00333 * NULL. This operation will return true if invoking it caused the 00334 * value of the current delivery to change, even if it was set to 00335 * NULL. 00336 * 00337 * @param[in] link a link object 00338 * @return true if the current delivery was changed 00339 */ 00340 PN_EXTERN bool pn_link_advance(pn_link_t *link); 00341 00342 /** 00343 * Get the credit balance for a link. 00344 * 00345 * Links use a credit based flow control scheme. Every receiver 00346 * maintains a credit balance that corresponds to the number of 00347 * deliveries that the receiver can accept at any given moment. As 00348 * more capacity becomes available at the receiver (see 00349 * ::pn_link_flow), it adds credit to this balance and communicates 00350 * the new balance to the sender. Whenever a delivery is 00351 * sent/received, the credit balance maintained by the link is 00352 * decremented by one. Once the credit balance at the sender reaches 00353 * zero, the sender must pause sending until more credit is obtained 00354 * from the receiver. 00355 * 00356 * Note that a sending link may still be used to send deliveries even 00357 * if pn_link_credit reaches zero, however those deliveries will end 00358 * up being buffered by the link until enough credit is obtained from 00359 * the receiver to send them over the wire. In this case the balance 00360 * reported by ::pn_link_credit will go negative. 00361 * 00362 * @param[in] link a link object 00363 * @return the credit balance for the link 00364 */ 00365 PN_EXTERN int pn_link_credit(pn_link_t *link); 00366 00367 /** 00368 * Get the number of queued deliveries for a link. 00369 * 00370 * Links may queue deliveries for a number of reasons, for example 00371 * there may be insufficient credit to send them to the receiver (see 00372 * ::pn_link_credit), or they simply may not have yet had a chance to 00373 * be written to the wire. This operation will return the number of 00374 * queued deliveries on a link. 00375 * 00376 * @param[in] link a link object 00377 * @return the number of queued deliveries for the link 00378 */ 00379 PN_EXTERN int pn_link_queued(pn_link_t *link); 00380 00381 /** 00382 * Get the remote view of the credit for a link. 00383 * 00384 * The remote view of the credit for a link differs from local view of 00385 * credit for a link by the number of queued deliveries. In other 00386 * words ::pn_link_remote_credit is defined to be ::pn_link_credit - 00387 * ::pn_link_queued. 00388 * 00389 * @param[in] link a link object 00390 * @return the remote view of the credit for a link 00391 */ 00392 PN_EXTERN int pn_link_remote_credit(pn_link_t *link); 00393 00394 /** 00395 * Get the drain flag for a link. 00396 * 00397 * If a link is in drain mode, then the sending endpoint of a link 00398 * must immediately use up all available credit on the link. If this 00399 * is not possible, the excess credit must be returned by invoking 00400 * ::pn_link_drained. Only the receiving endpoint can set the drain 00401 * mode. See ::pn_link_set_drain for details. 00402 * 00403 * @param[in] link a link object 00404 * @return true if and only if the link is in drain mode 00405 */ 00406 PN_EXTERN bool pn_link_get_drain(pn_link_t *link); 00407 00408 /** 00409 * Drain excess credit for a link. 00410 * 00411 * When a link is in drain mode, the sender must use all excess credit 00412 * immediately, and release any excess credit back to the receiver if 00413 * there are no deliveries available to send. 00414 * 00415 * When invoked on a sending link that is in drain mode, this 00416 * operation will release all excess credit back to the receiver and 00417 * return the number of credits released back to the sender. If the 00418 * link is not in drain mode, this operation is a noop. 00419 * 00420 * When invoked on a receiving link, this operation will return and 00421 * reset the number of credits the sender has released back to the 00422 * receiver. 00423 * 00424 * @param[in] link a link object 00425 * @return the number of credits drained 00426 */ 00427 PN_EXTERN int pn_link_drained(pn_link_t *link); 00428 00429 /** 00430 * Get the available deliveries hint for a link. 00431 * 00432 * The available count for a link provides a hint as to the number of 00433 * deliveries that might be able to be sent if sufficient credit were 00434 * issued by the receiving link endpoint. See ::pn_link_offered for 00435 * more details. 00436 * 00437 * @param[in] link a link object 00438 * @return the available deliveries hint 00439 */ 00440 PN_EXTERN int pn_link_available(pn_link_t *link); 00441 00442 /** 00443 * Describes the permitted/expected settlement behaviours of a sending 00444 * link. 00445 * 00446 * The sender settle mode describes the permitted and expected 00447 * behaviour of a sending link with respect to settling of deliveries. 00448 * See ::pn_delivery_settle for more details. 00449 */ 00450 typedef enum { 00451 PN_SND_UNSETTLED = 0, /**< The sender will send all deliveries 00452 initially unsettled. */ 00453 PN_SND_SETTLED = 1, /**< The sender will send all deliveries settled 00454 to the receiver. */ 00455 PN_SND_MIXED = 2 /**< The sender may send a mixure of settled and 00456 unsettled deliveries. */ 00457 } pn_snd_settle_mode_t; 00458 00459 /** 00460 * Describes the permitted/expected settlement behaviours of a 00461 * receiving link. 00462 * 00463 * The receiver settle mode describes the permitted and expected 00464 * behaviour of a receiving link with respect to settling of 00465 * deliveries. See ::pn_delivery_settle for more details. 00466 */ 00467 typedef enum { 00468 PN_RCV_FIRST = 0, /**< The receiver will settle deliveries 00469 regardless of what the sender does. */ 00470 PN_RCV_SECOND = 1 /**< The receiver will only settle deliveries 00471 after the sender settles. */ 00472 } pn_rcv_settle_mode_t; 00473 00474 /** 00475 * Get the local sender settle mode for a link. 00476 * 00477 * @param[in] link a link object 00478 * @return the local sender settle mode 00479 */ 00480 PN_EXTERN pn_snd_settle_mode_t pn_link_snd_settle_mode(pn_link_t *link); 00481 00482 /** 00483 * Get the local receiver settle mode for a link. 00484 * 00485 * @param[in] link a link object 00486 * @return the local receiver settle mode 00487 */ 00488 PN_EXTERN pn_rcv_settle_mode_t pn_link_rcv_settle_mode(pn_link_t *link); 00489 00490 /** 00491 * Set the local sender settle mode for a link. 00492 * 00493 * @param[in] link a link object 00494 * @param[in] mode the sender settle mode 00495 */ 00496 PN_EXTERN void pn_link_set_snd_settle_mode(pn_link_t *link, pn_snd_settle_mode_t mode); 00497 00498 /** 00499 * Set the local receiver settle mode for a link. 00500 * 00501 * @param[in] link a link object 00502 * @param[in] mode the receiver settle mode 00503 */ 00504 PN_EXTERN void pn_link_set_rcv_settle_mode(pn_link_t *link, pn_rcv_settle_mode_t mode); 00505 00506 /** 00507 * Get the remote sender settle mode for a link. 00508 * 00509 * @param[in] link a link object 00510 * @return the remote sender settle mode 00511 */ 00512 PN_EXTERN pn_snd_settle_mode_t pn_link_remote_snd_settle_mode(pn_link_t *link); 00513 00514 /** 00515 * Get the remote receiver settle mode for a link. 00516 * 00517 * @param[in] link a link object 00518 * @return the remote receiver settle mode 00519 */ 00520 PN_EXTERN pn_rcv_settle_mode_t pn_link_remote_rcv_settle_mode(pn_link_t *link); 00521 00522 /** 00523 * Get the number of unsettled deliveries for a link. 00524 * 00525 * @param[in] link a link object 00526 * @return the number of unsettled deliveries 00527 */ 00528 PN_EXTERN int pn_link_unsettled(pn_link_t *link); 00529 00530 /** 00531 * Get the first unsettled delivery for a link. 00532 * 00533 " @param[in] link a link object 00534 * @return a pointer to the first unsettled delivery on the link 00535 */ 00536 PN_EXTERN pn_delivery_t *pn_unsettled_head(pn_link_t *link); 00537 00538 /** 00539 * Get the next unsettled delivery on a link. 00540 * 00541 * @param[in] delivery a delivery object 00542 * @return the next unsettled delivery on the link 00543 */ 00544 PN_EXTERN pn_delivery_t *pn_unsettled_next(pn_delivery_t *delivery); 00545 00546 /** 00547 * @defgroup sender Sender 00548 * @{ 00549 */ 00550 00551 /** 00552 * Signal the availability of deliveries for a link. 00553 * 00554 * @param[in] sender a sender link object 00555 * @param[in] credit the number of deliveries potentially available 00556 * for transfer 00557 */ 00558 PN_EXTERN void pn_link_offered(pn_link_t *sender, int credit); 00559 00560 /** 00561 * Send message data for the current delivery on a link. 00562 * 00563 * @param[in] sender a sender link object 00564 * @param[in] bytes the start of the message data 00565 * @param[in] n the number of bytes of message data 00566 * @return the number of bytes sent, or an error code 00567 */ 00568 PN_EXTERN ssize_t pn_link_send(pn_link_t *sender, const char *bytes, size_t n); 00569 00570 //PN_EXTERN void pn_link_abort(pn_sender_t *sender); 00571 00572 /** @} */ 00573 00574 // receiver 00575 /** 00576 * @defgroup receiver Receiver 00577 * @{ 00578 */ 00579 00580 /** 00581 * Grant credit for incoming deliveries on a receiver. 00582 * 00583 * @param[in] receiver a receiving link object 00584 * @param[in] credit the amount to increment the link credit 00585 */ 00586 PN_EXTERN void pn_link_flow(pn_link_t *receiver, int credit); 00587 00588 /** 00589 * Grant credit for incoming deliveries on a receiver, and set drain 00590 * mode to true. 00591 * 00592 * Use ::pn_link_set_drain to set the drain mode explicitly. 00593 * 00594 * @param[in] receiver a receiving link object 00595 * @param[in] credit the amount to increment the link credit 00596 */ 00597 PN_EXTERN void pn_link_drain(pn_link_t *receiver, int credit); 00598 00599 /** 00600 * Set the drain mode on a link. 00601 * 00602 * @param[in] receiver a receiving link object 00603 * @param[in] drain the drain mode 00604 */ 00605 PN_EXTERN void pn_link_set_drain(pn_link_t *receiver, bool drain); 00606 00607 /** 00608 * Receive message data for the current delivery on a link. 00609 * 00610 * Use ::pn_delivery_pending on the current delivery to figure out how 00611 * much buffer space is needed. 00612 * 00613 * Note that the link API can be used to stream large messages across 00614 * the network, so just because there is no data to read does not 00615 * imply the message is complete. To ensure the entirety of the 00616 * message data has been read, either invoke ::pn_link_recv until 00617 * PN_EOS is returned, or verify that ::pn_delivery_partial is false, 00618 * and ::pn_delivery_pending is 0. 00619 * 00620 * @param[in] receiver a receiving link object 00621 * @param[in] bytes a pointer to an empty buffer 00622 * @param[in] n the buffer capacity 00623 * @return the number of bytes received, PN_EOS, or an error code 00624 */ 00625 PN_EXTERN ssize_t pn_link_recv(pn_link_t *receiver, char *bytes, size_t n); 00626 00627 /** 00628 * Check if a link is currently draining. 00629 * 00630 * A link is defined to be draining when drain mode is set to true, 00631 * and the sender still has excess credit. 00632 * 00633 * @param[in] receiver a receiving link object 00634 * @return true if the link is currently draining, false otherwise 00635 */ 00636 PN_EXTERN bool pn_link_draining(pn_link_t *receiver); 00637 00638 /** @} */ 00639 00640 /** @} 00641 */ 00642 00643 #ifdef __cplusplus 00644 } 00645 #endif 00646 00647 #endif /* link.h */ 00648