c/include/proton/delivery.h

#ifndef PROTON_DELIVERY_H
#define PROTON_DELIVERY_H 1

/*
 *
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 *
 */

#include <proton/import_export.h>
#include <proton/disposition.h>
#include <proton/type_compat.h>
#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @file
 *
 * @copybrief delivery
 *
 * @addtogroup delivery
 * @{
 */

/**
 * An AMQP delivery tag.
 */
typedef pn_bytes_t pn_delivery_tag_t;

/**
 * Construct a delivery tag.
 *
 * @param[in] bytes a pointer to the beginning of the tag
 * @param[in] size the size of the tag
 * @return the delivery tag
 */
PN_EXTERN pn_delivery_tag_t pn_dtag(const char *bytes, size_t size);

/**
 * Create a delivery on a link.
 *
 * Every delivery object within a link must be supplied with a unique
 * tag. Links maintain a sequence of delivery object in the order that
 * they are created.
 *
 * @param[in] link a link object
 * @param[in] tag the delivery tag
 * @return a newly created delivery, or NULL if there was an error
 */
PN_EXTERN pn_delivery_t *pn_delivery(pn_link_t *link, pn_delivery_tag_t tag);

/**
 * Get the application context that is associated with a delivery object.
 *
 * The application context for a delivery may be set using
 * ::pn_delivery_set_context.
 *
 * @param[in] delivery the delivery whose context is to be returned.
 * @return the application context for the delivery object
 */
PN_EXTERN void *pn_delivery_get_context(pn_delivery_t *delivery);

/**
 * Set a new application context for a delivery object.
 *
 * The application context for a delivery object may be retrieved using
 * ::pn_delivery_get_context.
 *
 * @param[in] delivery the delivery object
 * @param[in] context the application context
 */
PN_EXTERN void pn_delivery_set_context(pn_delivery_t *delivery, void *context);

/**
 * Get the attachments that are associated with a delivery object.
 *
 * @param[in] delivery the delivery whose attachments are to be returned.
 * @return the attachments for the delivery object
 */
PN_EXTERN pn_record_t *pn_delivery_attachments(pn_delivery_t *delivery);

/**
 * Get the tag for a delivery object.
 *
 * @param[in] delivery a delivery object
 * @return the delivery tag
 */
PN_EXTERN pn_delivery_tag_t pn_delivery_tag(pn_delivery_t *delivery);

/**
 * Get the parent link for a delivery object.
 *
 * @param[in] delivery a delivery object
 * @return the parent link
 */
PN_EXTERN pn_link_t *pn_delivery_link(pn_delivery_t *delivery);

/**
 * Get the local disposition for a delivery.
 *
 * The pointer returned by this object is valid until the delivery is
 * settled.
 *
 * @param[in] delivery a delivery object
 * @return a pointer to the local disposition
 */
PN_EXTERN pn_disposition_t *pn_delivery_local(pn_delivery_t *delivery);

/**
 * Get the local disposition state for a delivery.
 *
 * @param[in] delivery a delivery object
 * @return the local disposition state
 */
PN_EXTERN uint64_t pn_delivery_local_state(pn_delivery_t *delivery);

/**
 * Get the remote disposition for a delivery.
 *
 * The pointer returned by this object is valid until the delivery is
 * settled.
 *
 * @param[in] delivery a delivery object
 * @return a pointer to the remote disposition
 */
PN_EXTERN pn_disposition_t *pn_delivery_remote(pn_delivery_t *delivery);

/**
 * Get the remote disposition state for a delivery.
 *
 * @param[in] delivery a delivery object
 * @return the remote disposition state
 */
PN_EXTERN uint64_t pn_delivery_remote_state(pn_delivery_t *delivery);

/**
 * Check if a delivery is remotely settled.
 *
 * @param[in] delivery a delivery object
 * @return true if the delivery is settled at the remote endpoint, false otherwise
 */
PN_EXTERN bool pn_delivery_settled(pn_delivery_t *delivery);

/**
 * Get the amount of pending message data for a delivery.
 *
 * @param[in] delivery a delivery object
 * @return the amount of pending message data in bytes
 */
PN_EXTERN size_t pn_delivery_pending(pn_delivery_t *delivery);

/**
 * Check if a delivery only has partial message data.
 *
 * The receiver can expect more ::PN_DELIVERY events for this delivery containing
 * the remainder of this message.
 *
 * @param[in] delivery a delivery object
 * @return true if the delivery only contains part of a message, false otherwise
 */
PN_EXTERN bool pn_delivery_partial(pn_delivery_t *delivery);

/**
 * Check if a received delivery has been aborted.
 *
 * An aborted delivery means the sender cannot complete this message and the
 * receiver should discard any data already received. The link remains open for
 * future messages.
 *
 * You must still call pn_delivery_settle() to free local resources. An aborted
 * delivery consumes a credit, use pn_link_flow() to issue new credit as for a
 * successful delivery.
 *
 * Calling pn_link_recv() when the current delivery is aborted returns
 * ::PN_ABORTED.
 *
 * @see pn_delivery_abort()
 * @param[in] delivery a delivery object
 * @return true if the delivery has been aborted, false otherwise
 */
PN_EXTERN bool pn_delivery_aborted(pn_delivery_t *delivery);

/**
 * Check if a delivery is writable.
 *
 * A delivery is considered writable if it is the current delivery on
 * an outgoing link, and the link has positive credit.
 *
 * @param[in] delivery a delivery object
 * @return true if the delivery is writable, false otherwise
 */
PN_EXTERN bool pn_delivery_writable(pn_delivery_t *delivery);

/**
 * Check if a delivery is readable.
 *
 * A delivery is considered readable if it is the current delivery on
 * an incoming link.
 *
 * @param[in] delivery a delivery object
 * @return true if the delivery is readable, false otherwise
 */
PN_EXTERN bool pn_delivery_readable(pn_delivery_t *delivery);

/**
 * Check if a delivery is updated.
 *
 * A delivery is considered updated whenever the peer communicates a
 * new disposition for the delivery. Once a delivery becomes updated,
 * it will remain so until ::pn_delivery_clear is called.
 *
 * @param[in] delivery a delivery object
 * @return true if the delivery is updated, false otherwise
 */
PN_EXTERN bool pn_delivery_updated(pn_delivery_t *delivery);

/**
 * Update the disposition of a delivery.
 *
 * When update is invoked the updated disposition of the delivery will
 * be communicated to the peer.
 *
 * @param[in] delivery a delivery object
 * @param[in] state the updated delivery state
 */
PN_EXTERN void pn_delivery_update(pn_delivery_t *delivery, uint64_t state);

/**
 * Clear the updated flag for a delivery.
 *
 * See ::pn_delivery_updated.
 *
 * @param[in] delivery a delivery object
 */
PN_EXTERN void pn_delivery_clear(pn_delivery_t *delivery);

/**
 * Return true if delivery is the current delivery for its link.
 *
 * @param[in] delivery a delivery object
 * @return true if delivery is the current delivery for its link.
 */
PN_EXTERN bool pn_delivery_current(pn_delivery_t *delivery);

/**
 * Abort a delivery being sent.
 *
 * Aborting means the sender cannot complete this message. It will not send any
 * more data, and data sent so far should be discarded by the receiver.  The
 * link remains open for future messages.
 *
 * If some data has already been sent on the network, an AMQP "aborted" frame
 * will be sent to inform the peer. If no data has yet been sent, the delivery
 * will simply be forgotten.
 *
 * The delivery will be freed, and cannot be used after the call.
 *
 * @see pn_delivery_aborted()
 *
 * @param[in] delivery a delivery object
 */
PN_EXTERN void pn_delivery_abort(pn_delivery_t *delivery);

/**
 * Settle a delivery.
 *
 * A settled delivery can never be used again.
 *
 * @note If pn_delivery_current(delivery) is true before the call then
 * pn_link_advance(pn_delivery_link(deliver)) is called automatically.
 *
 * @param[in] delivery a delivery object
 */
PN_EXTERN void pn_delivery_settle(pn_delivery_t *delivery);

/**
 * Utility function for printing details of a delivery.
 *
 * @param[in] delivery a delivery object
 */
PN_EXTERN void pn_delivery_dump(pn_delivery_t *delivery);

/**
 * Check if a delivery is buffered.
 *
 * A delivery that is buffered has not yet been written to the wire.
 *
 * Note that returning false does not imply that a delivery was
 * definitely written to the wire. If false is returned, it is not
 * known whether the delivery was actually written to the wire or not.
 *
 * @param[in] delivery a delivery object
 * @return true if the delivery is buffered
 */
PN_EXTERN bool pn_delivery_buffered(pn_delivery_t *delivery);

/**
 * Extracts the first delivery on the connection that has pending
 * operations.
 *
 * Retrieves the first delivery on the Connection that has pending
 * operations. A readable delivery indicates message data is waiting
 * to be read. A writable delivery indicates that message data may be
 * sent. An updated delivery indicates that the delivery's disposition
 * has changed. A delivery will never be both readable and writable,
 * but it may be both readable and updated or both writable and
 * updated.
 *
 * @param[in] connection the connection
 * @return the first delivery object that needs to be serviced, else
 * NULL if none
 */
PN_DEPRECATED("Use the PN_DELIVERY event to track deliveries with pending operations")
PN_EXTERN pn_delivery_t *pn_work_head(pn_connection_t *connection);

/**
 * Get the next delivery on the connection that needs has pending
 * operations.
 *
 * @param[in] delivery the previous delivery retrieved from
 *                     either pn_work_head or pn_work_next
 * @return the next delivery that has pending operations, else
 * NULL if none
 */
PN_DEPRECATED("Use the PN_DELIVERY event to track deliveries with pending operations")
PN_EXTERN pn_delivery_t *pn_work_next(pn_delivery_t *delivery);

/**
 * @}
 */

#ifdef __cplusplus
}
#endif

#endif /* delivery.h */