net.kano.joscar.rvproto.directim
Class DirectImHeader

java.lang.Object
  DirectImHeader

All Implemented Interfaces:

LiveWritable

public final class DirectImHeader

extends java.lang.Object

implements LiveWritable

A data structure containing information about a Direct IM message or typing notification. Note that this is only a header and does not contain the message (and attached images or other media) itself.

Field Summary

static java.lang.String	DCVERSION_DEFAULT The Direct IM protocol version string used by WinAIM.
static long	FLAG_AUTORESPONSE A flag indicating that a message is an "auto-response."
static long	FLAG_TYPED A flag indicating, when combined with FLAG_TYPINGPACKET, that the user has typed a message, but has momentarily stopped typing.
static long	FLAG_TYPING A flag indicating, when combined with FLAG_TYPINGPACKET, that the user is typing a message.
static long	FLAG_TYPINGPACKET A flag indicating that a packet is a typing-notification packet.

Constructor Summary

DirectImHeader()
Creates a new direct IM header with all values set to -1 or null, depending on type.

DirectImHeader(DirectImHeader header)
Creates a new direct IM header object with the same properties as the given header object.

Method Summary

static DirectImHeader	createMessageHeader(ImEncodedString message) Creates a new direct IM header appropriate for sending the given message.
static DirectImHeader	createMessageHeader(ImEncodedString message, boolean autoresponse) Creates a new direct IM header appropriate for sending the given message.
static DirectImHeader	createTypedHeader() Creates a new Direct IM header that indicates that the user has typed a message, but has momentarily stopped typing.
static DirectImHeader	createTypingErasedHeader() Creates a new Direct IM header that indicates that the user has erased the message he or she had previously typed.
static DirectImHeader	createTypingHeader() Creates a new Direct IM header that indicates that the user is typing a message.
long	getDataLength() Returns the length of the message body data to follow this header.
java.lang.String	getDcVersion() Returns the direct IM protocol version string sent in this header.
ImEncodingParams	getEncoding() Returns an object describing the encoding being used for the message body to follow this header.
long	getFlags() Returns a set of bit flags for this header.
int	getHeaderSize() Returns the size of this header, in bytes, if read from an incoming stream.
long	getMessageId() Returns the message ID for this header.
java.lang.String	getScreenname() Returns the screenname sent in this header.
static DirectImHeader	readDirectIMHeader(java.io.InputStream in) Creates a new Direct IM header from the data in the given stream.
void	setDataLength(long dataLength) Sets the length of the message data to follow this header.
void	setDcVersion(java.lang.String dcVersion) Sets the direct connection version string to send in this header.
void	setDefaults() Sets some default values for this header.
void	setEncoding(ImEncodingParams encoding) Sets the encoding method used to encode the message body to follow this header.
void	setFlags(long flags) Sets the bit flags to send in this header.
void	setMessageId(long messageId) Sets the message ID for this header.
void	setScreenname(java.lang.String sn) Sets the screenname to send in this header.
java.lang.String	toString()
void	write(java.io.OutputStream out) Writes this header to the given stream.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

DCVERSION_DEFAULT

public static final java.lang.String DCVERSION_DEFAULT

The Direct IM protocol version string used by WinAIM.

See Also:

Constant Field Values

FLAG_TYPINGPACKET

public static final long FLAG_TYPINGPACKET

A flag indicating that a packet is a typing-notification packet. Note that this flag is always sent in typing notification headers, whether the header means that the user is typing, has stopped typing, or has erased what he has typed.

If this flag is combined with FLAG_TYPING, the user is currently typing a message.
If this flag is combined with FLAG_TYPED, the user has typed a message, but has momentarily stopped typing.
If this flag is not sent with either FLAG_TYPING or FLAG_TYPED, the user has erased any message he had previously been typing.

See Also:

Constant Field Values

FLAG_TYPING

public static final long FLAG_TYPING

A flag indicating, when combined with FLAG_TYPINGPACKET, that the user is typing a message.

See Also:

Constant Field Values

FLAG_TYPED

public static final long FLAG_TYPED

A flag indicating, when combined with FLAG_TYPINGPACKET, that the user has typed a message, but has momentarily stopped typing.

See Also:

Constant Field Values

FLAG_AUTORESPONSE

public static final long FLAG_AUTORESPONSE

A flag indicating that a message is an "auto-response."

See Also:

Constant Field Values

Constructor Detail

DirectImHeader

public DirectImHeader()

Creates a new direct IM header with all values set to -1 or null, depending on type.

See Also:

setDefaults()

DirectImHeader

public DirectImHeader(DirectImHeader header)

Creates a new direct IM header object with the same properties as the given header object.

Parameters:

header - a direct IM header object to copy

Method Detail

createTypingHeader

public static DirectImHeader createTypingHeader()

Creates a new Direct IM header that indicates that the user is typing a message. That is, this method creates a direct IM header with all defaults set and the flags FLAG_TYPINGPACKET | FLAG_TYPING.

Returns:

a new Direct IM header indicating that the user is typing a message

createTypedHeader

public static DirectImHeader createTypedHeader()

Creates a new Direct IM header that indicates that the user has typed a message, but has momentarily stopped typing. That is, this method creates a direct IM header with all defaults set and the flags FLAG_TYPINGPACKET | FLAG_TYPED.

Returns:

a new Direct IM header indicating that the user has typed a message, but has stopped typing

createTypingErasedHeader

public static DirectImHeader createTypingErasedHeader()

Creates a new Direct IM header that indicates that the user has erased the message he or she had previously typed. That is, this method creates a direct IM header with all defaults set and the flags FLAG_TYPINGPACKET.

Returns:

a new Direct IM header indicating that the user is typing a message

createMessageHeader

public static DirectImHeader createMessageHeader(ImEncodedString message)

Creates a new direct IM header appropriate for sending the given message. Note that the returned header does not contain the given message; rather, it is simply appropriate for sending as a header for the message body itself.

Parameters:

message - a message for which a Direct IM header should be returned

Returns:

a direct IM header appropriate for sending with the given message

createMessageHeader

public static DirectImHeader createMessageHeader(ImEncodedString message,
                                                 boolean autoresponse)

Creates a new direct IM header appropriate for sending the given message. Note that the returned header does not contain the given message; rather, it is simply appropriate for sending as a header for the message body itself.

Parameters:

message - a message for which a Direct IM header should be returned

autoresponse - whether or not the given message is an "auto-response"

Returns:

a direct IM header appropriate for sending with the given message

readDirectIMHeader

public static DirectImHeader readDirectIMHeader(java.io.InputStream in)
                                         throws java.io.IOException

Creates a new Direct IM header from the data in the given stream. Note that this method will block until a full header has been read from the given stream. This method will return null if no valid header can be read.

Parameters:

in - the stream from which to read a direct IM header

Returns:

a direct IM header read from the given stream, or null if none could be read

Throws:

java.io.IOException - if an I/O error occurs

getDcVersion

public final java.lang.String getDcVersion()

Returns the direct IM protocol version string sent in this header. This is normally DCVERSION_DEFAULT.

Returns:

the direct IM protocol version string sent in this header

getMessageId

public final long getMessageId()

Returns the message ID for this header.

Returns:

this header's message ID

getDataLength

public final long getDataLength()

Returns the length of the message body data to follow this header.

Returns:

the length of the data that will follow this header, in bytes

getEncoding

public final ImEncodingParams getEncoding()

Returns an object describing the encoding being used for the message body to follow this header.

Returns:

an object describing the encoding to be used to decode the message body that follows this header

getFlags

public final long getFlags()

Returns a set of bit flags for this header. Will normally be a combination of any of the FLAG_* flags. To test for a particular flag, one might use code resembling the following:

if ((directImHeader.getFlags() & DirectImHeader.FLAG_AUTORESPONSE) != 0) {
    System.out.println("Message is an auto-response!");
}
 

Returns:

a set of flags contained in this direct IM header

getScreenname

public final java.lang.String getScreenname()

Returns the screenname sent in this header. Note that this value should be ignored, as while it is supposed to be the screenname of the user sending this message, any screenname can actually be sent. (WinAIM ignores this value.)

Returns:

the screenname sent in this header

getHeaderSize

public final int getHeaderSize()

Returns the size of this header, in bytes, if read from an incoming stream. Note that this value will be -1 if this header was not read from an incoming stream.

Returns:

the size of this header, in bytes, or -1 if this header was not read from an incoming stream

setDcVersion

public final void setDcVersion(java.lang.String dcVersion)

Sets the direct connection version string to send in this header.

Parameters:

dcVersion - the direct connection version string to send in this header

setMessageId

public final void setMessageId(long messageId)

Sets the message ID for this header.

Parameters:

messageId - the message ID to send in this header

setDataLength

public final void setDataLength(long dataLength)

Sets the length of the message data to follow this header.

Parameters:

dataLength - the data length value to send in this header

setEncoding

public final void setEncoding(ImEncodingParams encoding)

Sets the encoding method used to encode the message body to follow this header. Note that if this value is null, a charset and charsubset of 0 and 0 will be sent with this command, suitable for sending a typing notification or other non-message header.

Parameters:

encoding - the encoding method used to encode the message body to follow this header, or null for none

setFlags

public final void setFlags(long flags)

Sets the bit flags to send in this header. This should be a bitwise combination of any of the FLAG_* constants.

Parameters:

flags - a set of flags to send in this header

setScreenname

public final void setScreenname(java.lang.String sn)

Sets the screenname to send in this header. This value is supposed to be the screenname of the user sending the header, but in practice it is simply ignored by the official clients (as it should be). Note that by sending a different screenname allows one to remotely spoof messages from other users when chatting with someone using Gaim.

Parameters:

sn - a screenname to send in this header

setDefaults

public final void setDefaults()

Sets some default values for this header. Calling this method is equivalent to excecuting the following code:

header.setDcVersion(DirectImHeader.DCVERSION_DEFAULT);
header.setDataLength(0);
header.setEncoding(null);
header.setFlags(0);
header.setScreenname("");
 

Note that a call to write(java.io.OutputStream) will never throw an IllegalArgumentException if it has not been modified since a call to this method.

write

public void write(java.io.OutputStream out)
           throws java.io.IOException,
                  java.lang.IllegalArgumentException

Writes this header to the given stream. Note that this method will not write any data to the stream if any fields in this header object are invalid. Valid values for individual fields are as follows:

Field	Must be...
dcVersion	non-null
dataLength	nonnegative (0 or greater)
encoding	non-null
flags	nonnegative (0 or greater)
screenname	non-null

Specified by:

write in interface LiveWritable

Parameters:

out - the stream to which to write

Throws:

java.io.IOException - if an I/O error occurs

java.lang.IllegalArgumentException - if a field is invalid

toString

public java.lang.String toString()