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