class Qpid::Proton::Message

A Message represents an addressable quantity of data.

Message Body

The message body can be set using the body= method. The message will then attempt to determine how exactly to encode the content.

Examples

To create a message for sending:

# send a simple text message
msg = Qpid::Proton::Message.new
msg.body = "STATE: update"

# send a binary chunk of data
data = File.binread("/home/qpid/binfile.tar.gz")
msg = Qpid::Proton::Message.new
msg.body = Qpid::Proton::BinaryString.new(data)

Public Class Methods

new(body = nil) click to toggle source

Creates a new Message instance.

# File lib/core/message.rb, line 132
def initialize(body = nil)
  @impl = Cproton.pn_message
  ObjectSpace.define_finalizer(self, self.class.finalize!(@impl))
  @properties = {}
  @instructions = {}
  @annotations = {}
  self.body = body unless body.nil?
end

Public Instance Methods

[](name) click to toggle source

Retrieves the value for the specified property name. If not found, then it returns nil.

# File lib/core/message.rb, line 563
def [](name)
  @properties[name]
end
[]=(name, value) click to toggle source

Assigns the value given to the named property.

Arguments

  • name - the property name

  • value - the property value

# File lib/core/message.rb, line 556
def []=(name, value)
  @properties[name] = value
end
address() click to toggle source

Returns the destination address.

# File lib/core/message.rb, line 342
def address
  Cproton.pn_message_get_address(@impl)
end
address=(address) click to toggle source

Sets the destination address.

Options

  • address - the address

# File lib/core/message.rb, line 336
def address=(address)
  Cproton.pn_message_set_address(@impl, address)
end
annotations() click to toggle source

Returns the annotations for this message.

# File lib/core/message.rb, line 587
def annotations
  @annotations
end
annotations=(annotations) click to toggle source

Assigns annotations to this message.

# File lib/core/message.rb, line 593
def annotations=(annotations)
  @annotations = annotations
end
body() click to toggle source

Returns the body property of the message.

# File lib/core/message.rb, line 599
def body
  @body
end
body=(body) click to toggle source

Assigns a new value to the body of the message.

# File lib/core/message.rb, line 605
def body=(body)
  @body = body
end
clear() click to toggle source

Clears the state of the Message. This allows a single instance of Message to be reused.

# File lib/core/message.rb, line 165
def clear
  Cproton.pn_message_clear(@impl)
  @properties.clear unless @properties.nil?
  @instructions.clear unless @instructions.nil?
  @annotations.clear unless @annotations.nil?
  @body = nil
end
content() click to toggle source

@deprecated use {#body}

# File lib/core/message.rb, line 416
def content
  size = 16
  loop do
    result = Cproton.pn_message_save(@impl, size)
    error = result[0]
    data = result[1]
    if error == Qpid::Proton::Error::OVERFLOW
      size = size * 2
    else
      check(error)
      return data
    end
  end
end
content=(content) click to toggle source

@deprecated use {#body=}

# File lib/core/message.rb, line 411
def content=(content)
  Cproton.pn_message_load(@impl, content)
end
content_encoding() click to toggle source

Returns the content encoding type.

# File lib/core/message.rb, line 443
def content_encoding
  Cproton.pn_message_get_content_encoding(@impl)
end
content_encoding=(encoding) click to toggle source

Sets the content encoding type.

Options

  • encoding - the content encoding

# File lib/core/message.rb, line 437
def content_encoding=(encoding)
  Cproton.pn_message_set_content_encoding(@impl, encoding)
end
content_type() click to toggle source

Returns the content type

# File lib/core/message.rb, line 406
def content_type
  Cproton.pn_message_get_content_type(@impl)
end
content_type=(content_type) click to toggle source

Sets the content type.

Options

# File lib/core/message.rb, line 400
def content_type=(content_type)
  Cproton.pn_message_set_content_type(@impl, content_type)
end
correlation_id() click to toggle source

Returns the correlation id.

# File lib/core/message.rb, line 390
def correlation_id
  Cproton.pn_message_get_correlation_id(@impl)
end
correlation_id=(id) click to toggle source

Sets the correlation id.

Options

  • id - the correlation id

# File lib/core/message.rb, line 384
def correlation_id=(id)
  Cproton.pn_message_set_correlation_id(@impl, id)
end
creation_time() click to toggle source

Returns the creation time.

# File lib/core/message.rb, line 479
def creation_time
  Cproton.pn_message_get_creation_time(@impl)
end
creation_time=(time) click to toggle source

Sets the creation time.

Options

  • time - the creation time

# File lib/core/message.rb, line 471
def creation_time=(time)
  raise TypeError.new("invalid time: #{time}") if time.nil?
  raise ::ArgumentError.new("time cannot be negative") if time < 0
  Cproton.pn_message_set_creation_time(@impl, time)
end
decode(encoded) click to toggle source

Decodes a message from supplied AMQP data and returns the number of bytes consumed.

Options

  • encoded - the encoded data

# File lib/core/message.rb, line 61
def decode(encoded)
  check(Cproton.pn_message_decode(@impl, encoded, encoded.length))

  post_decode
end
delete_property(name) click to toggle source

Deletes the named property.

# File lib/core/message.rb, line 569
def delete_property(name)
  @properties.delete(name)
end
delivery_count() click to toggle source

Returns the delivery count for the message.

This is the number of delivery attempts for the given message.

# File lib/core/message.rb, line 287
def delivery_count
  Cproton.pn_message_get_delivery_count(@impl)
end
delivery_count=(count) click to toggle source

Sets the delivery count for the message.

See ::delivery_count for more details.

Options

  • count - the delivery count

# File lib/core/message.rb, line 277
def delivery_count=(count)
  raise ::ArgumentError.new("invalid count: #{count}") if not count.is_a?(Numeric)
  raise RangeError.new("count out of range: #{count}") if count < 0
  Cproton.pn_message_set_delivery_count(@impl, count.floor)
end
durable() click to toggle source

Returns the durable property.

The durable property indicates that the emessage should be held durably by any intermediaries taking responsibility for the message.

Examples

msg = Qpid::Proton::Message.new
msg.durable = true
# File lib/core/message.rb, line 214
def durable
  Cproton.pn_message_is_durable(@impl)
end
durable=(state) click to toggle source

Sets the durable flag.

See ::durable for more details on message durability.

Options

  • state - the durable state

# File lib/core/message.rb, line 199
def durable=(state)
  raise TypeError.new("state cannot be nil") if state.nil?
  Cproton.pn_message_set_durable(@impl, state)
end
encode() click to toggle source

Encodes the message.

# File lib/core/message.rb, line 92
def encode
  pre_encode
  size = 16
  loop do
    error, data = Cproton::pn_message_encode(@impl, size)
    if error == Qpid::Proton::Error::OVERFLOW
      size *= 2
    else
      check(error)
      return data
    end
  end
end
errno() click to toggle source

Returns the most recent error number.

# File lib/core/message.rb, line 175
def errno
  Cproton.pn_message_errno(@impl)
end
error() click to toggle source

Returns the most recent error message.

# File lib/core/message.rb, line 181
def error
  Cproton.pn_error_text(Cproton.pn_message_error(@impl))
end
error?() click to toggle source

Returns whether there is currently an error reported.

# File lib/core/message.rb, line 187
def error?
  !Cproton.pn_message_errno(@impl).zero?
end
expires() click to toggle source

Returns the expiration time.

# File lib/core/message.rb, line 461
def expires
  Cproton.pn_message_get_expiry_time(@impl)
end
expires=(time) click to toggle source

Sets the expiration time.

Options

  • time - the expiry time

# File lib/core/message.rb, line 453
def expires=(time)
  raise TypeError.new("invalid expiry time: #{time}") if time.nil?
  raise ::ArgumentError.new("expiry time cannot be negative: #{time}") if time < 0
  Cproton.pn_message_set_expiry_time(@impl, time)
end
first_acquirer=(state) click to toggle source

Sets whether this is the first time the message was acquired.

See ::first_acquirer? for more details.

Options

  • state - true if claiming the message

# File lib/core/message.rb, line 264
def first_acquirer=(state)
  raise TypeError.new("invalid state: #{state}") if state.nil? || !([TrueClass, FalseClass].include?(state.class))
  Cproton.pn_message_set_first_acquirer(@impl, state)
end
first_acquirer?() click to toggle source

Returns whether this is the first acquirer.

# File lib/core/message.rb, line 294
def first_acquirer?
  Cproton.pn_message_is_first_acquirer(@impl)
end
group_id() click to toggle source

Returns the group id.

# File lib/core/message.rb, line 495
def group_id
  Cproton.pn_message_get_group_id(@impl)
end
group_id=(id) click to toggle source

Sets the group id.

Options

  • id - the group id

# File lib/core/message.rb, line 489
def group_id=(id)
  Cproton.pn_message_set_group_id(@impl, id)
end
group_sequence() click to toggle source

Returns the group sequence number.

# File lib/core/message.rb, line 512
def group_sequence
  Cproton.pn_message_get_group_sequence(@impl)
end
group_sequence=(seq) click to toggle source

Sets the group sequence number.

Options

  • seq - the sequence number

# File lib/core/message.rb, line 505
def group_sequence=(seq)
  raise TypeError.new("invalid seq: #{seq}") if seq.nil?
  Cproton.pn_message_set_group_sequence(@impl, seq)
end
id() click to toggle source

Returns the message id.

# File lib/core/message.rb, line 310
def id
  Cproton.pn_message_get_id(@impl)
end
id=(id) click to toggle source

Sets the message id.

Options

  • id = the id

# File lib/core/message.rb, line 304
def id=(id)
  Cproton.pn_message_set_id(@impl, id)
end
instructions() click to toggle source

Returns the instructions for this message.

# File lib/core/message.rb, line 575
def instructions
  @instructions
end
instructions=(instr) click to toggle source

Assigns instructions to this message.

# File lib/core/message.rb, line 581
def instructions=(instr)
  @instructions = instr
end
priority() click to toggle source

Returns the priority.

# File lib/core/message.rb, line 234
def priority
  Cproton.pn_message_get_priority(@impl)
end
priority=(priority) click to toggle source

Sets the priority.

NOTE: Priority values are limited to the range [0,255].

Options

  • priority - the priority value

# File lib/core/message.rb, line 226
def priority=(priority)
  raise TypeError.new("invalid priority: #{priority}") if not priority.is_a?(Numeric)
  raise RangeError.new("priority out of range: #{priority}") if ((priority > 255) || (priority < 0))
  Cproton.pn_message_set_priority(@impl, priority.floor)
end
properties() click to toggle source

Returns the list of property names for associated with this message.

Examples

msg.properties.each do |name|
end
# File lib/core/message.rb, line 539
def properties
  @properties
end
properties=(properties) click to toggle source

Replaces the entire set of properties with the specified hash.

# File lib/core/message.rb, line 545
def properties=(properties)
  @properties = properties
end
proton_send(sender, tag = nil) click to toggle source

@private

# File lib/core/message.rb, line 45
def proton_send(sender, tag = nil)
  dlv = sender.delivery(tag || sender.delivery_tag)
  encoded = self.encode
  sender.stream(encoded)
  sender.advance
  dlv.settle if sender.snd_settle_mode == Link::SND_SETTLED
  return dlv
end
reply_to() click to toggle source

Returns the reply-to address

# File lib/core/message.rb, line 374
def reply_to
  Cproton.pn_message_get_reply_to(@impl)
end
reply_to=(address) click to toggle source

Sets the reply-to address.

Options

  • address - the reply-to address

# File lib/core/message.rb, line 368
def reply_to=(address)
  Cproton.pn_message_set_reply_to(@impl, address)
end
reply_to_group_id() click to toggle source

Returns the reply-to group id.

# File lib/core/message.rb, line 528
def reply_to_group_id
  Cproton.pn_message_get_reply_to_group_id(@impl)
end
reply_to_group_id=(id) click to toggle source

Sets the reply-to group id.

Options

  • id - the id

# File lib/core/message.rb, line 522
def reply_to_group_id=(id)
  Cproton.pn_message_set_reply_to_group_id(@impl, id)
end
subject() click to toggle source

Returns the subject

# File lib/core/message.rb, line 358
def subject
  Cproton.pn_message_get_subject(@impl)
end
subject=(subject) click to toggle source

Sets the subject.

Options

  • subject - the subject

# File lib/core/message.rb, line 352
def subject=(subject)
  Cproton.pn_message_set_subject(@impl, subject)
end
to_s() click to toggle source
# File lib/core/message.rb, line 141
def to_s
  tmp = Cproton.pn_string("")
  Cproton.pn_inspect(@impl, tmp)
  result = Cproton.pn_string_get(tmp)
  Cproton.pn_free(tmp)
  return result
end
ttl() click to toggle source

Returns the time-to-live, in milliseconds.

# File lib/core/message.rb, line 252
def ttl
  Cproton.pn_message_get_ttl(@impl)
end
ttl=(time) click to toggle source

Sets the time-to-live for the message.

Options

  • time - the time in milliseconds

# File lib/core/message.rb, line 244
def ttl=(time)
  raise TypeError.new("invalid ttl: #{time}") if not time.is_a?(Numeric)
  raise RangeError.new("ttl out of range: #{time}") if ((time.to_i < 0))
  Cproton.pn_message_set_ttl(@impl, time.floor)
end
user_id() click to toggle source

Returns the user id.

# File lib/core/message.rb, line 326
def user_id
  Cproton.pn_message_get_user_id(@impl)
end
user_id=(id) click to toggle source

Sets the user id.

Options

  • id - the user id

# File lib/core/message.rb, line 320
def user_id=(id)
  Cproton.pn_message_set_user_id(@impl, id)
end