Interface IBytesMessage

A BytesMessage object is used to send a message containing a stream of uninterpreted bytes. It inherits from the Message interface and adds a bytes message body. The receiver of the message supplies the interpretation of the bytes.

This message type is for client encoding of existing message formats. If possible, one of the other self-defining message types should be used instead.

Although the NMS API allows the use of message properties with byte messages, they are typically not used, since the inclusion of properties may affect the format.

When the message is first created, and when ClearBody is called, the body of the message is in write-only mode. After the first call to Reset has been made, the message body is in read-only mode. After a message has been sent, the client that sent it can retain and modify it without affecting the message that has been sent. The same message object can be sent multiple times. When a message has been received, the provider has called Reset so that the message body is in read-only mode for the client.

If ClearBody is called on a message in read-only mode, the message body is cleared and the message is in write-only mode.

If a client attempts to read a message in write-only mode, a MessageNotReadableException is thrown.

If a client attempts to write a message in read-only mode, a MessageNotWriteableException is thrown.

Inherited Members

IMessage.Acknowledge()

IMessage.AcknowledgeAsync()

IMessage.ClearBody()

IMessage.ClearProperties()

IMessage.Properties

IMessage.CorrelationID

IMessage.Destination

IMessage.TimeToLive

IMessage.MessageId

IMessage.DeliveryMode

IMessage.Priority

IMessage.Redelivered

IMessage.ReplyTo

IMessage.Timestamp

IMessage.Type

IMessage.DeliveryTime

IMessage.Body<T>()

IMessage.IsBodyAssignableTo(Type)

Namespace: CodersRealm.AmqpClient

Assembly: CodersRealm.AmqpClient.dll

Syntax

public interface IBytesMessage : IMessage

Properties

BodyLength

Declaration

long BodyLength { get; }

Property Value

Type	Description
long	Gets the number of bytes of the message body when the message is in read-only mode. The value returned can be used to allocate a byte array. The value returned is the entire length of the message body, regardless of where the pointer for reading the message is currently located.

Exceptions

Type	Condition
MessageNotReadableException	Thrown when the Message is in write-only mode.
AmqpException	Thrown when there is an unhandled exception thrown from the provider.

Content

Gets or sets the number of bytes in the message body.

Declaration

byte[] Content { get; set; }

Property Value

Type	Description
byte[]

Methods

ReadBoolean()

Reads a boolean from the Message Stream.

Declaration

bool ReadBoolean()

Returns

Type	Description
bool	A bool

Exceptions

Type	Condition
MessageNotReadableException	Thrown when the Message is in write-only mode.
MessageEOFException	Thrown when an unexpected end of bytes has been reached.
AmqpException	Thrown when there is an unhandled exception thrown from the provider.

ReadByte()

Reads a byte from the Message Stream.

Declaration

byte ReadByte()

Returns

Type	Description
byte	A byte

Exceptions

Type	Condition
MessageNotReadableException	Thrown when the Message is in write-only mode.
MessageEOFException	Thrown when an unexpected end of bytes has been reached.
AmqpException	Thrown when there is an unhandled exception thrown from the provider.

ReadBytes(byte[])

Reads a byte array from the bytes message stream.

If the length of array value is less than the number of bytes remaining to be read from the stream, the array should be filled. A subsequent call reads the next increment, and so on.

If the number of bytes remaining in the stream is less than the length of array value, the bytes should be read into the array. The return value of the total number of bytes read will be less than the length of the array, indicating that there are no more bytes left to be read from the stream. The next read of the stream returns -1.

Declaration

int ReadBytes(byte[] value)

Parameters

Type	Name	Description
byte[]	value	The byte array that will be used as a buffer to read into.

Returns

Type	Description
int	A int The number of bytes read into the passed byte array, or -1 if there are no more bytes left to be read from the stream.

Exceptions

Type	Condition
AmqpException	Thrown when there is an unhandled exception thrown from the provider.
MessageNotReadableException	Thrown when the Message is in write-only mode.

ReadBytes(byte[], int)

Reads a portion of the bytes message stream.

If the length of array value is less than the number of bytes remaining to be read from the stream, the array should be filled. A subsequent call reads the next increment, and so on.

If the number of bytes remaining in the stream is less than the length of array value, the bytes should be read into the array. The return value of the total number of bytes read will be less than the length of the array, indicating that there are no more bytes left to be read from the stream. The next read of the stream returns -1.

If length is negative, or length is greater than the length of the array value, then an Exception is thrown. No bytes will be read from the stream for this exception case.

Declaration

int ReadBytes(byte[] value, int length)

Parameters

Type	Name	Description
byte[]	value	The byte array that will be used as a buffer to read into.
int	length	The amount of bytes to read into the buffer.

Returns

Type	Description
int	A int The number of bytes read into the passed byte array, or -1 if there are no more bytes left to be read from the stream.

Exceptions

Type	Condition
MessageNotReadableException	Thrown when the Message is in write-only mode.
AmqpException	Thrown when there is an unhandled exception thrown from the provider.

ReadChar()

Reads a char from the Message Stream.

Declaration

char ReadChar()

Returns

Type	Description
char	A char

Exceptions

Type	Condition
MessageNotReadableException	Thrown when the Message is in write-only mode.
MessageEOFException	Thrown when an unexpected end of bytes has been reached.
AmqpException	Thrown when there is an unhandled exception thrown from the provider.

ReadDouble()

Reads an double from the Message Stream.

Declaration

double ReadDouble()

Returns

Type	Description
double	A double

Exceptions

Type	Condition
MessageNotReadableException	Thrown when the Message is in write-only mode.
MessageEOFException	Thrown when an unexpected end of bytes has been reached.
AmqpException	Thrown when there is an unhandled exception thrown from the provider.

ReadInt16()

Reads a Short from the Message Stream.

Declaration

short ReadInt16()

Returns

Type	Description
short	A short

Exceptions

Type	Condition
MessageNotReadableException	Thrown when the Message is in write-only mode.
MessageEOFException	Thrown when an unexpected end of bytes has been reached.
AmqpException	Thrown when there is an unhandled exception thrown from the provider.

ReadInt32()

Reads an int from the Message Stream.

Declaration

int ReadInt32()

Returns

Type	Description
int	A int

Exceptions

Type	Condition
MessageNotReadableException	Thrown when the Message is in write-only mode.
MessageEOFException	Thrown when an unexpected end of bytes has been reached.
AmqpException	Thrown when there is an unhandled exception thrown from the provider.

ReadInt64()

Reads a long from the Message Stream.

Declaration

long ReadInt64()

Returns

Type	Description
long	A long

Exceptions

Type	Condition
MessageNotReadableException	Thrown when the Message is in write-only mode.
MessageEOFException	Thrown when an unexpected end of bytes has been reached.
AmqpException	Thrown when there is an unhandled exception thrown from the provider.

ReadSingle()

Reads a float from the Message Stream.

Declaration

float ReadSingle()

Returns

Type	Description
float	A float

Exceptions

Type	Condition
MessageNotReadableException	Thrown when the Message is in write-only mode.
MessageEOFException	Thrown when an unexpected end of bytes has been reached.
AmqpException	Thrown when there is an unhandled exception thrown from the provider.

ReadString()

Reads a string that has been encoded using a modified UTF-8 format from the bytes message stream.

Declaration

string ReadString()

Returns

Type	Description
string	A string

Exceptions

Type	Condition
MessageNotReadableException	Thrown when the Message is in write-only mode.
MessageEOFException	Thrown when an unexpected end of bytes has been reached.
AmqpException	Thrown when there is an unhandled exception thrown from the provider.

Reset()

Puts the message body in read-only mode and repositions the stream of bytes to the beginning.

Declaration

void Reset()

Exceptions

Type	Condition
MessageFormatException	Thrown when the Message has an invalid format.
AmqpException	Thrown when there is an unhandled exception thrown from the provider.

WriteBoolean(bool)

Write a one byte value to the message stream representing the boolean value passed.

Declaration

void WriteBoolean(bool value)

Parameters

Type	Name	Description
bool	value	A bool

Exceptions

Type	Condition
MessageNotWriteableException	Thrown when the Message is in read-only mode.
AmqpException	Thrown when there is an unhandled exception thrown from the provider.

WriteByte(byte)

Writes a byte to the Message stream.

Declaration

void WriteByte(byte value)

Parameters

Type	Name	Description
byte	value	A byte

Exceptions

Type	Condition
MessageNotWriteableException	Thrown when the Message is in read-only mode.
AmqpException	Thrown when there is an unhandled exception thrown from the provider.

WriteBytes(byte[])

Writes a byte array to the bytes message stream.

Declaration

void WriteBytes(byte[] value)

Parameters

Type	Name	Description
byte[]	value	A byte

Exceptions

Type	Condition
MessageNotWriteableException	Thrown when the Message is in read-only mode.
AmqpException	Thrown when there is an unhandled exception thrown from the provider.

WriteBytes(byte[], int, int)

Writes a portion of a byte array to the bytes message stream.

Declaration

void WriteBytes(byte[] value, int offset, int length)

Parameters

Type	Name	Description
byte[]	value	A byte
int	offset	A int
int	length	A int

Exceptions

Type	Condition
MessageNotWriteableException	Thrown when the Message is in read-only mode.
AmqpException	Thrown when there is an unhandled exception thrown from the provider.

WriteChar(char)

Write a two byte value to the message stream representing the character value passed. High byte first.

Declaration

void WriteChar(char value)

Parameters

Type	Name	Description
char	value	A char

Exceptions

Type	Condition
MessageNotWriteableException	Thrown when the Message is in read-only mode.
AmqpException	Thrown when there is an unhandled exception thrown from the provider.

WriteDouble(double)

Write a eight byte value to the message stream representing the double value passed. High byte first.

Declaration

void WriteDouble(double value)

Parameters

Type	Name	Description
double	value	A double

Exceptions

Type	Condition
MessageNotWriteableException	Thrown when the Message is in read-only mode.
AmqpException	Thrown when there is an unhandled exception thrown from the provider.

WriteInt16(short)

Write a two byte value to the message stream representing the short value passed. High byte first.

Declaration

void WriteInt16(short value)

Parameters

Type	Name	Description
short	value	A short

Exceptions

Type	Condition
MessageNotWriteableException	Thrown when the Message is in read-only mode.
AmqpException	Thrown when there is an unhandled exception thrown from the provider.

WriteInt32(int)

Write a four byte value to the message stream representing the integer value passed. High byte first.

Declaration

void WriteInt32(int value)

Parameters

Type	Name	Description
int	value	A int

Exceptions

Type	Condition
MessageNotWriteableException	Thrown when the Message is in read-only mode.
AmqpException	Thrown when there is an unhandled exception thrown from the provider.

WriteInt64(long)

Write a eight byte value to the message stream representing the long value passed. High byte first.

Declaration

void WriteInt64(long value)

Parameters

Type	Name	Description
long	value	A long

Exceptions

Type	Condition
MessageNotWriteableException	Thrown when the Message is in read-only mode.
AmqpException	Thrown when there is an unhandled exception thrown from the provider.

WriteObject(object)

Writes an object to the bytes message stream.

This method works only for the objectified primitive object types (Int32, Double, Boolean ...), String objects, and byte arrays.

Declaration

void WriteObject(object value)

Parameters

Type	Name	Description
object	value	A object the object in the .NET programming language to be written; it must not be null

Exceptions

Type	Condition
MessageFormatException	Thrown when the Message has an invalid format.
MessageNotWriteableException	Thrown when the Message is in read-only mode.
AmqpException	Thrown when there is an unhandled exception thrown from the provider.

WriteSingle(float)

Write a four byte value to the message stream representing the float value passed. High byte first.

Declaration

void WriteSingle(float value)

Parameters

Type	Name	Description
float	value	A float

Exceptions

Type	Condition
MessageNotWriteableException	Thrown when the Message is in read-only mode.
AmqpException	Thrown when there is an unhandled exception thrown from the provider.

WriteString(string)

Writes a string to the bytes message stream using UTF-8 encoding in a machine-independent manner.

Declaration

void WriteString(string value)

Parameters

Type	Name	Description
string	value	A string

Exceptions

Type	Condition
MessageNotWriteableException	Thrown when the Message is in read-only mode.
AmqpException	Thrown when there is an unhandled exception thrown from the provider.