class Qpid::Proton::Transport

A transport is used by a connection to interface with the network.

A transport is associated with, at most, one Connection.

Client And Server Mode

Initially, a transport is configured to be a client tranpsort. It can be configured to act as a server when it is created.

A client transport initiates outgoing connections.

A client transport must be configured with the protocol layers to use and cannot configure itself automatically.

A server transport accepts incoming connections. It can automatically configure itself to include the various protocol layers depending on the incoming protocol headers.

Tracing Data

Data can be traced into and out of the transport programmatically by setting the trace level to one of the defined trace values (TRACE_RAW, TRACE_FRM or TRACE_DRV). Tracing can also be turned off programmatically by setting the trace level to TRACE_OFF.

@example

# turns on frame tracing
@transport.trace = Qpid::Proton::Transport::TRACE_FRM

# ... do something where the frames are of interest, such as debugging

# turn tracing off again
@transport.trace = Qpid::Proton::Transport::TRACE_NONE

Tracing can also be enabled from the command line by defining the similarly named environment variable before starting a Proton application:

@example

# enable tracing from the command line
PN_TRACE_FRM=1 ruby my_proton_app.rb

Constants

CLIENT

@private

PROTON_METHOD_PREFIX

@private

SERVER

@private

TRACE_DRV

Log driver related events; i.e., initialization, end of stream, etc.

TRACE_FRM

Log frames into/out of the transport.

TRACE_OFF

Turn logging off entirely.

TRACE_RAW

Log raw binary data into/out of the transport.

Public Class Methods

new(mode = nil, impl = Cproton.pn_transport) click to toggle source

Creates a new transport instance.

@param mode [Integer] The transport mode, either CLIENT or SERVER @param impl [pn_transport_t] Should not be used.

@raise [TransportError] If the mode is invalid.

# File lib/core/transport.rb, line 226
def initialize(mode = nil, impl = Cproton.pn_transport)
  @impl = impl
  if mode == SERVER
    Cproton.pn_transport_set_server(@impl)
  elsif (!mode.nil? && mode != CLIENT)
    raise TransportError.new("cannot create transport for mode: #{mode}")
  end
  self.class.store_instance(self, :pn_transport_attachments)
end
wrap(impl) click to toggle source

@private

# File lib/core/transport.rb, line 213
def self.wrap(impl)
  return nil if impl.nil?

  self.fetch_instance(impl, :pn_transport_attachments) || Transport.new(nil, impl)
end

Public Instance Methods

bind(connection) click to toggle source

Binds to the given connection.

@param connection [Connection] The connection.

# File lib/core/transport.rb, line 259
def bind(connection)
  Cproton.pn_transport_bind(@impl, connection.impl)
end
close_head() click to toggle source

Indicate that the output has closed.

Tells the transport that no more output will be popped.

@raise [TransportError] If an error occurs.

# File lib/core/transport.rb, line 366
def close_head
  Cproton.pn_transport_close_head(@impl)
end
close_tail() click to toggle source

Indicate that the input has reached EOS (end of stream).

This tells the transport that no more input will be forthcoming.

@raise [TransportError] If an error occurs.

# File lib/core/transport.rb, line 332
def close_tail
  Cproton.pn_transport_close_tail(@impl)
end
condition() click to toggle source

Returns additional information about the condition of the transport.

When a TRANSPORT_ERROR event occurs, this operaiton can be used to access the details of the error condition.

The object returned is valid until the Transport is discarded.

# File lib/core/transport.rb, line 251
def condition
  condition_to_object Cproton.pn_transport_condition(@impl)
end
connection() click to toggle source

Return the AMQP connection associated with the transport.

@return [Connection, nil] The bound connection, or nil.

# File lib/core/transport.rb, line 286
def connection
  Connection.wrap(Cproton.pn_transport_connection(@impl))
end
log(message) click to toggle source

Log a message to the transport's logging mechanism.

This can be using in a debugging scenario as the message will be prepended with the transport's identifier.

@param message [String] The message to be logged.

# File lib/core/transport.rb, line 297
def log(message)
  Cproton.pn_transport_log(@impl, message)
end
peek(size) click to toggle source

Returns the specified number of bytes from the transport's buffers.

@param size [Integer] The number of bytes to return.

@return [String] The data peeked.

@raise [TransportError] If an error occurs.

# File lib/core/transport.rb, line 344
def peek(size)
  cd, out = Cproton.pn_transport_peek(@impl, size)
  return nil if cd == Qpid::Proton::Error::EOS
  raise TransportError.new if cd < -1
  out
end
pop(size) click to toggle source

Removes the specified number of bytes from the pending output queue following the transport's head pointer.

@param size [Integer] The number of bytes to remove.

# File lib/core/transport.rb, line 356
def pop(size)
  Cproton.pn_transport_pop(@impl, size)
end
process(size) click to toggle source

Process input data following the tail pointer.

Calling this function will cause the transport to consume the specified number of bytes of input occupying the free space following the tail pointer. It may also change the value for tail, as well as the amount of free space reported by capacity.

@param size [Integer] The number of bytes to process.

@raise [TransportError] If an error occurs.

# File lib/core/transport.rb, line 322
def process(size)
  Cproton.pn_transport_process(@impl, size)
end
push(data) click to toggle source

Pushes the supplied bytes into the tail of the transport.

@param data [String] The bytes to be pushed.

@return [Integer] The number of bytes pushed.

# File lib/core/transport.rb, line 307
def push(data)
  Cproton.pn_transport_push(@impl, data, data.length)
end
quiesced?() click to toggle source

Returns whether the transport has any buffered data.

@return [Boolean] True if the transport has no buffered data.

# File lib/core/transport.rb, line 240
def quiesced?
  Cproton.pn_transport_quiesced(@impl)
end
sasl() click to toggle source

Create, or return existing, SSL object for the transport. @return [SASL] the SASL object

# File lib/core/transport.rb, line 391
def sasl
  SASL.new(self)
end
ssl(domain = nil, session_details = nil) click to toggle source

Creates, or returns an existing, SSL object for the transport.

@param domain [SSLDomain] The SSL domain. @param session_details [SSLDetails] The SSL session details.

@return [SSL] The SSL object.

# File lib/core/transport.rb, line 402
def ssl(domain = nil, session_details = nil)
  @ssl ||= SSL.create(self, domain, session_details) if @ssl.nil?
end
ssl?() click to toggle source

@private

# File lib/core/transport.rb, line 407
def ssl?
  !@ssl.nil?
end
tick(now) click to toggle source

Process any pending transport timer events.

This method should be called after all pending input has been processed by the transport (see input), and before generating output (see output).

It returns the deadline for the next pending timer event, if any art present.

@param now [Time] The timestamp.

@return [Integer] If non-zero, the expiration time of the next pending

timer event for the transport. The caller must invoke #tick again at
least once at or before this deadline occurs.
# File lib/core/transport.rb, line 385
def tick(now)
  Cproton.pn_transport_tick(@impl, now)
end
trace(level) click to toggle source

Updates the transports trace flags.

@param level [Integer] The trace level.

@see TRACE_OFF @see TRACE_RAW @see TRACE_FRM @see TRACE_DRV

# File lib/core/transport.rb, line 278
def trace(level)
  Cproton.pn_transport_trace(@impl, level)
end
unbind() click to toggle source

Unbinds from the previous connection.

# File lib/core/transport.rb, line 265
def unbind
  Cproton.pn_transport_unbind(@impl)
end