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
Namespace: Apache.NMS
Assembly: Apache.NMS.dll
Syntax
public interface IBytesMessage : IMessage
Properties
| Improve this Doc View SourceBodyLength
Declaration
long BodyLength { get; }
Property Value
Type | Description |
---|---|
System.Int64 | 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. |
NMSException | Thrown when there is an unhandled exception thrown from the provider. |
Content
Declaration
byte[] Content { get; set; }
Property Value
Type | Description |
---|---|
System.Byte[] |
Methods
| Improve this Doc View SourceReadBoolean()
Reads a boolean from the Message Stream.
Declaration
bool ReadBoolean()
Returns
Type | Description |
---|---|
System.Boolean | A System.Boolean |
Exceptions
Type | Condition |
---|---|
MessageNotReadableException | Thrown when the Message is in write-only mode. |
MessageEOFException | Thrown when an unexpected end of bytes has been reached. |
NMSException | 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 |
---|---|
System.Byte | A System.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. |
NMSException | 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 |
---|---|---|
System.Byte[] | value | The byte array that will be used as a buffer to read into. |
Returns
Type | Description |
---|---|
System.Int32 | A System.Int32 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 |
---|---|
NMSException | Thrown when there is an unhandled exception thrown from the provider. |
MessageNotReadableException | Thrown when the Message is in write-only mode. |
ReadBytes(Byte[], Int32)
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 |
---|---|---|
System.Byte[] | value | The byte array that will be used as a buffer to read into. |
System.Int32 | length | The amount of bytes to read into the buffer. |
Returns
Type | Description |
---|---|
System.Int32 | A System.Int32 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. |
NMSException | 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 |
---|---|
System.Char | A System.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. |
NMSException | 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 |
---|---|
System.Double | A System.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. |
NMSException | 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 |
---|---|
System.Int16 | A System.Int16 |
Exceptions
Type | Condition |
---|---|
MessageNotReadableException | Thrown when the Message is in write-only mode. |
MessageEOFException | Thrown when an unexpected end of bytes has been reached. |
NMSException | 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 |
---|---|
System.Int32 | A System.Int32 |
Exceptions
Type | Condition |
---|---|
MessageNotReadableException | Thrown when the Message is in write-only mode. |
MessageEOFException | Thrown when an unexpected end of bytes has been reached. |
NMSException | 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 |
---|---|
System.Int64 | A System.Int64 |
Exceptions
Type | Condition |
---|---|
MessageNotReadableException | Thrown when the Message is in write-only mode. |
MessageEOFException | Thrown when an unexpected end of bytes has been reached. |
NMSException | 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 |
---|---|
System.Single | A System.Single |
Exceptions
Type | Condition |
---|---|
MessageNotReadableException | Thrown when the Message is in write-only mode. |
MessageEOFException | Thrown when an unexpected end of bytes has been reached. |
NMSException | 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 |
---|---|
System.String | A System.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. |
NMSException | 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. |
NMSException | Thrown when there is an unhandled exception thrown from the provider. |
WriteBoolean(Boolean)
Write a one byte value to the message stream representing the boolean value passed.
Declaration
void WriteBoolean(bool value)
Parameters
Type | Name | Description |
---|---|---|
System.Boolean | value | A System.Boolean |
Exceptions
Type | Condition |
---|---|
MessageNotWriteableException | Thrown when the Message is in read-only mode. |
NMSException | 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 |
---|---|---|
System.Byte | value | A System.Byte |
Exceptions
Type | Condition |
---|---|
MessageNotWriteableException | Thrown when the Message is in read-only mode. |
NMSException | 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 |
---|---|---|
System.Byte[] | value | A System.Byte |
Exceptions
Type | Condition |
---|---|
MessageNotWriteableException | Thrown when the Message is in read-only mode. |
NMSException | Thrown when there is an unhandled exception thrown from the provider. |
WriteBytes(Byte[], Int32, Int32)
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 |
---|---|---|
System.Byte[] | value | A System.Byte |
System.Int32 | offset | A System.Int32 |
System.Int32 | length | A System.Int32 |
Exceptions
Type | Condition |
---|---|
MessageNotWriteableException | Thrown when the Message is in read-only mode. |
NMSException | 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 |
---|---|---|
System.Char | value | A System.Char |
Exceptions
Type | Condition |
---|---|
MessageNotWriteableException | Thrown when the Message is in read-only mode. |
NMSException | 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 |
---|---|---|
System.Double | value | A System.Double |
Exceptions
Type | Condition |
---|---|
MessageNotWriteableException | Thrown when the Message is in read-only mode. |
NMSException | Thrown when there is an unhandled exception thrown from the provider. |
WriteInt16(Int16)
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 |
---|---|---|
System.Int16 | value | A System.Int16 |
Exceptions
Type | Condition |
---|---|
MessageNotWriteableException | Thrown when the Message is in read-only mode. |
NMSException | Thrown when there is an unhandled exception thrown from the provider. |
WriteInt32(Int32)
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 |
---|---|---|
System.Int32 | value | A System.Int32 |
Exceptions
Type | Condition |
---|---|
MessageNotWriteableException | Thrown when the Message is in read-only mode. |
NMSException | Thrown when there is an unhandled exception thrown from the provider. |
WriteInt64(Int64)
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 |
---|---|---|
System.Int64 | value | A System.Int64 |
Exceptions
Type | Condition |
---|---|
MessageNotWriteableException | Thrown when the Message is in read-only mode. |
NMSException | 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 |
---|---|---|
System.Object | value | A System.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. |
NMSException | Thrown when there is an unhandled exception thrown from the provider. |
WriteSingle(Single)
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 |
---|---|---|
System.Single | value | A System.Single |
Exceptions
Type | Condition |
---|---|
MessageNotWriteableException | Thrown when the Message is in read-only mode. |
NMSException | 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 |
---|---|---|
System.String | value | A System.String |
Exceptions
Type | Condition |
---|---|
MessageNotWriteableException | Thrown when the Message is in read-only mode. |
NMSException | Thrown when there is an unhandled exception thrown from the provider. |