blob: 347eadb043dfaaeffd67644d16cdf02375a7b007 [file] [log] [blame]
* 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
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
#include "./fwd.hpp"
#include "./internal/export.hpp"
#include "./duration.hpp"
#include "./timestamp.hpp"
#include "./value.hpp"
#include "./map.hpp"
#include "./internal/pn_unique_ptr.hpp"
#include <proton/type_compat.h>
#include <string>
#include <vector>
/// @file
/// @copybrief proton::message
struct pn_message_t;
namespace proton {
/// An AMQP message.
/// Value semantics: A message can be copied or assigned to make a new
/// message.
class message {
/// A map of string keys and AMQP scalar values.
typedef map<std::string, scalar> property_map;
/// A map of AMQP annotation keys and AMQP values.
typedef map<annotation_key, value> annotation_map;
/// Create an empty message.
PN_CPP_EXTERN message();
/// Copy a message.
PN_CPP_EXTERN message(const message&);
/// Copy a message.
PN_CPP_EXTERN message& operator=(const message&);
/// Move a message.
PN_CPP_EXTERN message(message&&);
/// Move a message.
PN_CPP_EXTERN message& operator=(message&&);
/// Create a message with its body set from any value that can be
/// converted to a proton::value.
PN_CPP_EXTERN message(const value& x);
PN_CPP_EXTERN ~message();
/// @name Basic properties and methods
/// @{
/// Clear the message content and properties.
PN_CPP_EXTERN void clear();
/// Set the message ID.
/// The message ID uniquely identifies a message within a
/// messaging system.
PN_CPP_EXTERN void id(const message_id&);
/// Get the message ID.
PN_CPP_EXTERN message_id id() const;
/// Set the user name or ID.
PN_CPP_EXTERN void user(const std::string&);
/// Get the user name or ID.
PN_CPP_EXTERN std::string user() const;
/// Encode entire message into a byte vector, growing it if
/// necessary.
PN_CPP_EXTERN void encode(std::vector<char>&) const;
/// Return encoded message as a byte vector.
PN_CPP_EXTERN std::vector<char> encode() const;
/// Decode from string data into the message.
PN_CPP_EXTERN void decode(const std::vector<char>&);
/// @}
/// @name Routing
/// @{
/// Set the destination address.
PN_CPP_EXTERN void to(const std::string&);
/// Get the destination address.
PN_CPP_EXTERN std::string to() const;
/// @cond INTERNAL
/// These are aliases for to()
PN_CPP_EXTERN void address(const std::string&);
PN_CPP_EXTERN std::string address() const;
/// @endcond
/// Set the address for replies.
PN_CPP_EXTERN void reply_to(const std::string&);
/// Get the address for replies.
PN_CPP_EXTERN std::string reply_to() const;
/// Set the ID for matching related messages.
PN_CPP_EXTERN void correlation_id(const message_id&);
/// Get the ID for matching related messages.
PN_CPP_EXTERN message_id correlation_id() const;
/// @}
/// @name Content
/// @{
/// Set the body. Equivalent to `body() = x`.
PN_CPP_EXTERN void body(const value& x);
/// Get the body.
PN_CPP_EXTERN const value& body() const;
/// Get a reference to the body that can be modified in place.
PN_CPP_EXTERN value& body();
/// Set the subject.
PN_CPP_EXTERN void subject(const std::string&);
/// Get the subject.
PN_CPP_EXTERN std::string subject() const;
/// Set the content type of the body.
PN_CPP_EXTERN void content_type(const std::string&);
/// Get the content type of the body.
PN_CPP_EXTERN std::string content_type() const;
/// Set the content encoding of the body.
PN_CPP_EXTERN void content_encoding(const std::string&);
/// Get the content encoding of the body.
PN_CPP_EXTERN std::string content_encoding() const;
/// Set the expiration time.
PN_CPP_EXTERN void expiry_time(timestamp);
/// Get the expiration time.
PN_CPP_EXTERN timestamp expiry_time() const;
/// Set the creation time.
PN_CPP_EXTERN void creation_time(timestamp);
/// Get the creation time.
PN_CPP_EXTERN timestamp creation_time() const;
/// Get the inferred flag.
/// The inferred flag for a message indicates how the message
/// content is encoded into AMQP sections. If the inferred is true
/// then binary and list values in the body of the message will be
/// encoded as AMQP DATA and AMQP SEQUENCE sections,
/// respectively. If inferred is false, then all values in the
/// body of the message will be encoded as AMQP VALUE sections
/// regardless of their type.
PN_CPP_EXTERN bool inferred() const;
/// Set the inferred flag.
PN_CPP_EXTERN void inferred(bool);
/// @}
/// @name Transfer headers
/// @{
/// Get the durable flag.
/// The durable flag indicates that any parties taking
/// responsibility for the message must durably store the content.
PN_CPP_EXTERN bool durable() const;
/// Set the durable flag.
PN_CPP_EXTERN void durable(bool);
/// Get the TTL.
/// The TTL (time to live) for a message determines how long a
/// message is considered live. When a message is held for
/// retransmit, the TTL is decremented. Once the TTL reaches zero,
/// the message is considered dead. Once a message is considered
/// dead, it may be dropped.
PN_CPP_EXTERN duration ttl() const;
/// Set the TTL.
PN_CPP_EXTERN void ttl(duration);
/// Get the priority.
/// The priority of a message impacts ordering guarantees. Within
/// a given ordered context, higher priority messages may jump
/// ahead of lower priority messages.
/// The default value set on newly constructed messages is message::default_priority.
PN_CPP_EXTERN uint8_t priority() const;
/// Set the priority.
PN_CPP_EXTERN void priority(uint8_t);
/// Get the first acquirer flag.
/// When set to true, the first acquirer flag for a message
/// indicates that the recipient of the message is the first
/// recipient to acquire the message, i.e. there have been no
/// failed delivery attempts to other acquirers. Note that this
/// does not mean the message has not been delivered to, but not
/// acquired, by other recipients.
// XXX The triple-not in the last sentence above is confusing.
PN_CPP_EXTERN bool first_acquirer() const;
/// Set the first acquirer flag.
PN_CPP_EXTERN void first_acquirer(bool);
/// Get the delivery count.
/// The delivery count field tracks how many attempts have been
/// made to deliver a message.
PN_CPP_EXTERN uint32_t delivery_count() const;
/// Get the delivery count.
PN_CPP_EXTERN void delivery_count(uint32_t);
/// @}
/// @name Message groups
/// @{
/// Set the message group ID.
PN_CPP_EXTERN void group_id(const std::string&);
/// Get the message group ID.
PN_CPP_EXTERN std::string group_id() const;
/// Set the reply-to group ID.
PN_CPP_EXTERN void reply_to_group_id(const std::string&);
/// Get the reply-to group ID.
PN_CPP_EXTERN std::string reply_to_group_id() const;
/// Get the group sequence.
/// The group sequence of a message identifies the relative
/// ordering of messages within a group. The default value for the
/// group sequence of a message is zero.
PN_CPP_EXTERN int32_t group_sequence() const;
/// Set the group sequence for a message.
PN_CPP_EXTERN void group_sequence(int32_t);
/// @}
/// @name Extended attributes
/// @{
/// Get the application properties map. It can
/// be modified in place.
PN_CPP_EXTERN property_map& properties();
/// Examine the application properties map.
PN_CPP_EXTERN const property_map& properties() const;
/// Get the message annotations map. It can
/// be modified in place.
PN_CPP_EXTERN annotation_map& message_annotations();
/// Examine the message annotations map.
PN_CPP_EXTERN const annotation_map& message_annotations() const;
/// Get the delivery annotations map. It can
/// be modified in place.
PN_CPP_EXTERN annotation_map& delivery_annotations();
/// Examine the delivery annotations map.
PN_CPP_EXTERN const annotation_map& delivery_annotations() const;
/// @}
/// Default priority assigned to new messages.
PN_CPP_EXTERN static const uint8_t default_priority;
/// Human readable string representation
friend PN_CPP_EXTERN std::ostream& operator<<(std::ostream&, const message&);
/// @cond INTERNAL
struct impl;
pn_message_t* pn_msg() const;
struct impl& impl() const;
mutable pn_message_t* pn_msg_;
PN_CPP_EXTERN friend void swap(message&, message&);
/// @endcond
/// Human readable string representation
PN_CPP_EXTERN std::string to_string(const message&);
} // proton