net.kano.joscar.rvproto.directim
Class DirectImHeader

java.lang.Object
  extended byDirectImHeader
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:
FieldMust be...
dcVersionnon-null
dataLengthnonnegative (0 or greater)
encodingnon-null
flagsnonnegative (0 or greater)
screennamenon-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()