/*
* 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
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
namespace Apache.NMS
{
///
///
/// 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.
///
public interface IBytesMessage : IMessage
{
byte[] Content { get; set; }
///
/// 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.
///
///
/// Thrown when the Message is in write-only mode.
///
///
/// Thrown when there is an unhandled exception thrown from the provider.
///
long BodyLength { get; }
///
/// Reads a byte from the Message Stream.
///
///
/// A
///
///
/// Thrown when the Message is in write-only mode.
///
///
/// Thrown when an unexpected end of bytes has been reached.
///
///
/// Thrown when there is an unhandled exception thrown from the provider.
///
byte ReadByte();
///
/// Writes a byte to the Message stream.
///
///
/// A
///
///
/// Thrown when the Message is in read-only mode.
///
///
/// Thrown when there is an unhandled exception thrown from the provider.
///
void WriteByte( byte value );
///
/// Reads a boolean from the Message Stream.
///
///
/// A
///
///
/// Thrown when the Message is in write-only mode.
///
///
/// Thrown when an unexpected end of bytes has been reached.
///
///
/// Thrown when there is an unhandled exception thrown from the provider.
///
bool ReadBoolean();
///
/// Write a one byte value to the message stream representing the boolean
/// value passed.
///
///
/// A
///
///
/// Thrown when the Message is in read-only mode.
///
///
/// Thrown when there is an unhandled exception thrown from the provider.
///
void WriteBoolean( bool value );
///
/// Reads a char from the Message Stream.
///
///
/// A
///
///
/// Thrown when the Message is in write-only mode.
///
///
/// Thrown when an unexpected end of bytes has been reached.
///
///
/// Thrown when there is an unhandled exception thrown from the provider.
///
char ReadChar();
///
/// Write a two byte value to the message stream representing the character
/// value passed. High byte first.
///
///
/// A
///
///
/// Thrown when the Message is in read-only mode.
///
///
/// Thrown when there is an unhandled exception thrown from the provider.
///
void WriteChar( char value );
///
/// Reads a Short from the Message Stream.
///
///
/// A
///
///
/// Thrown when the Message is in write-only mode.
///
///
/// Thrown when an unexpected end of bytes has been reached.
///
///
/// Thrown when there is an unhandled exception thrown from the provider.
///
short ReadInt16();
///
/// Write a two byte value to the message stream representing the short
/// value passed. High byte first.
///
///
/// A
///
///
/// Thrown when the Message is in read-only mode.
///
///
/// Thrown when there is an unhandled exception thrown from the provider.
///
void WriteInt16( short value );
///
/// Reads an int from the Message Stream.
///
///
/// A
///
///
/// Thrown when the Message is in write-only mode.
///
///
/// Thrown when an unexpected end of bytes has been reached.
///
///
/// Thrown when there is an unhandled exception thrown from the provider.
///
int ReadInt32();
///
/// Write a four byte value to the message stream representing the integer
/// value passed. High byte first.
///
///
/// A
///
///
/// Thrown when the Message is in read-only mode.
///
///
/// Thrown when there is an unhandled exception thrown from the provider.
///
void WriteInt32( int value );
///
/// Reads a long from the Message Stream.
///
///
/// A
///
///
/// Thrown when the Message is in write-only mode.
///
///
/// Thrown when an unexpected end of bytes has been reached.
///
///
/// Thrown when there is an unhandled exception thrown from the provider.
///
long ReadInt64();
///
/// Write a eight byte value to the message stream representing the long
/// value passed. High byte first.
///
///
/// A
///
///
/// Thrown when the Message is in read-only mode.
///
///
/// Thrown when there is an unhandled exception thrown from the provider.
///
void WriteInt64( long value );
///
/// Reads a float from the Message Stream.
///
///
/// A
///
///
/// Thrown when the Message is in write-only mode.
///
///
/// Thrown when an unexpected end of bytes has been reached.
///
///
/// Thrown when there is an unhandled exception thrown from the provider.
///
float ReadSingle();
///
/// Write a four byte value to the message stream representing the float
/// value passed. High byte first.
///
///
/// A
///
///
/// Thrown when the Message is in read-only mode.
///
///
/// Thrown when there is an unhandled exception thrown from the provider.
///
void WriteSingle( float value );
///
/// Reads an double from the Message Stream.
///
///
/// A
///
///
/// Thrown when the Message is in write-only mode.
///
///
/// Thrown when an unexpected end of bytes has been reached.
///
///
/// Thrown when there is an unhandled exception thrown from the provider.
///
double ReadDouble();
///
/// Write a eight byte value to the message stream representing the double
/// value passed. High byte first.
///
///
/// A
///
///
/// Thrown when the Message is in read-only mode.
///
///
/// Thrown when there is an unhandled exception thrown from the provider.
///
void WriteDouble( double value );
///
/// 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.
///
///
/// The byte array that will be used as a buffer to read into.
///
///
/// A
/// 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.
///
///
/// Thrown when there is an unhandled exception thrown from the provider.
///
///
/// Thrown when the Message is in write-only mode.
///
int ReadBytes( byte[] value );
///
/// 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.
///
///
/// The byte array that will be used as a buffer to read into.
///
///
/// The amount of bytes to read into the buffer.
///
///
/// A
/// 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.
///
///
/// Thrown when the Message is in write-only mode.
///
///
/// Thrown when there is an unhandled exception thrown from the provider.
///
int ReadBytes( byte[] value, int length );
///
/// Writes a byte array to the bytes message stream.
///
///
/// A
///
///
/// Thrown when the Message is in read-only mode.
///
///
/// Thrown when there is an unhandled exception thrown from the provider.
///
void WriteBytes( byte[] value );
///
/// Writes a portion of a byte array to the bytes message stream.
///
///
/// A
///
///
/// A
///
///
/// A
///
///
/// Thrown when the Message is in read-only mode.
///
///
/// Thrown when there is an unhandled exception thrown from the provider.
///
void WriteBytes( byte[] value, int offset, int length );
///
/// Reads a string that has been encoded using a modified UTF-8 format from the bytes
/// message stream.
///
///
/// A
///
///
/// Thrown when the Message is in write-only mode.
///
///
/// Thrown when an unexpected end of bytes has been reached.
///
///
/// Thrown when there is an unhandled exception thrown from the provider.
///
string ReadString();
///
/// Writes a string to the bytes message stream using UTF-8 encoding in a
/// machine-independent manner.
///
///
/// A
///
///
/// Thrown when the Message is in read-only mode.
///
///
/// Thrown when there is an unhandled exception thrown from the provider.
///
void WriteString( string value );
///
/// 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.
///
///
/// A
/// the object in the .NET programming language to be written; it must not be null
///
///
/// Thrown when the Message has an invalid format.
///
///
/// Thrown when the Message is in read-only mode.
///
///
/// Thrown when there is an unhandled exception thrown from the provider.
///
void WriteObject( System.Object value );
///
/// Puts the message body in read-only mode and repositions the stream of bytes to the beginning.
///
///
/// Thrown when the Message has an invalid format.
///
///
/// Thrown when there is an unhandled exception thrown from the provider.
///
void Reset();
}
}