|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectnet.kano.joscar.BinaryTools
Provides a set of methods for converting binary data sent over an OSCAR
connection to various logical structures.
Note that for all types such that get[type]
and
write[type]
exist, the two methods are inverses:
calling getLong
on a block written by writeLong
will return the original value written.
The methods in this class attempt to be very robust: in the cases of the
four-, two-, and one-byte unsigned integers (as in writeUShort(java.io.OutputStream, int)
),
if the given value is too large to fit into that size a block, it will be
wrapped (for example, writeUShort(out, 65537)
would be written
to the stream as if writeUShort(out, 1)
had been called). See
UINT_MAX
, USHORT_MAX
, and UBYTE_MAX
for the
maximum values such methods can take without wrapping. Note that those values
are not appropriate for the right-hand side of of a modulo operation
(like 65537 % BinaryTools.USHORT_MAX
), as these are
maxima. (An appropriate operation, if one were necessary, would be
65537 % (BinaryTools.USHORT_MAX + 1)
.)
Another area in which the methods attempt to be robust is that except for
getLong
, none of these methods declare any
exceptions. If a get[type](ByteBlock, int)
method is
passed a byte block that is too small, it simply returns -1
(this is okay because these methods only return unsigned values).
Lastly, it is important to note that all numbers transferred over OSCAR in
unsigned format. Why do getLong
and
writeLong
exist, you may ask, when they work with signed
long
s? Let me start by saying that nowhere in the OSCAR protocol
is an eight-byte integer used. Why do these methods exist at all?, you may
now ask. The answer is simple: IM and Rendezvous ID's are eight bytes,
and are effectively represented as Java's long
. Whether these
values are read as signed or unsigned matters not, as the long
is only an internal representation just as a ByteBlock
is an
internal representation of a block of bytes. I hope that explanation was
clear enough.
MiscTools
,
OscarTools
Field Summary | |
static short |
UBYTE_MAX
Represents the largest value a one-byte unsigned integer can have. |
static long |
UINT_MAX
Represents the largest value a four-byte unsigned integer can have. |
static int |
USHORT_MAX
Represents the largest value a two-byte unsigned integer can have. |
Method Summary | |
static java.lang.String |
describeData(ByteBlock data)
Returns a string describing each byte in the given block in generic unsigned hexadecimal dump notation. |
static byte[] |
getAsciiBytes(java.lang.String string)
Returns a block of data representing the given US-ASCII string. |
static java.lang.String |
getAsciiString(ByteBlock data)
Returns a String representing the given block of ASCII
characters.
|
static java.net.Inet4Address |
getIPFromBytes(ByteBlock data,
int pos)
Returns an IP address stored in the given byte block. |
static long |
getLong(ByteBlock data,
int pos)
Returns the signed long stored in the given data
block. |
static byte[] |
getLong(long number)
Returns a block of eight bytes representing the given signed long in binary format. |
static StringBlock |
getNullPadded(ByteBlock block)
Reads a null-padded ASCII string from the start of the given block. |
static short |
getUByte(ByteBlock data,
int pos)
Returns an unsigned one-byte integer stored in the given block. |
static byte[] |
getUByte(int number)
Returns a single-byte block representing the given unsigned value in binary format. |
static long |
getUInt(ByteBlock data,
int pos)
Returns the unsigned integer stored in the given data block. |
static byte[] |
getUInt(long number)
Returns a four-byte block representing the given unsigned value in binary format. |
static int |
getUShort(ByteBlock data,
int pos)
Returns an unsigned two-byte integer stored in the given block. |
static byte[] |
getUShort(int number)
Returns a two-byte block representing the given unsigned value in binary format. |
static void |
writeLong(java.io.OutputStream out,
long number)
Writes the given signed long to the given stream.
|
static void |
writeNullPadded(java.io.OutputStream out,
ByteBlock block,
int len)
Writes the given block to the given stream, padded to a given length with null bytes ( 0x00 ). |
static void |
writeUByte(java.io.OutputStream out,
int number)
Writes a single (unsigned) byte representing the given unsigned value to the given stream. |
static void |
writeUInt(java.io.OutputStream out,
long number)
Writes a block of four bytes representing the given unsigned value to the given stream. |
static void |
writeUShort(java.io.OutputStream out,
int number)
Writes a block of two bytes representing the given unsigned value to the given stream. |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
public static final long UINT_MAX
public static final int USHORT_MAX
public static final short UBYTE_MAX
Method Detail |
public static long getLong(ByteBlock data, int pos) throws java.lang.ArrayIndexOutOfBoundsException
long
stored in the given data
block. The returned long
represents the first eight bytes
after index pos
of data
; that is, the byte at
index pos
will be the first byte read, and index
pos+7
the last.
data
- the block of data to read frompos
- the starting index of data
to read from
long
representing the value stored in the
first eight bytes of the given data block after the given
position
java.lang.ArrayIndexOutOfBoundsException
- if there are fewer than eight
bytes in data
writeLong(java.io.OutputStream, long)
,
getLong(long)
public static long getUInt(ByteBlock data, int pos)
pos
. If there are fewer than four
bytes at pos
, -1
is returned.
long
because all values of an unsigned four-byte
integer cannot be stored in a four-byte signed integer, Java's
int
.
data
- the data block from which to readpos
- the starting index of data
to read from
-1
if fewer than four
bytes are present in the blockwriteUInt(java.io.OutputStream, long)
,
getUInt(long)
public static int getUShort(ByteBlock data, int pos)
pos
. If there are fewer than two
bytes at pos
, -1
is returned.
int
because all values of
an unsigned two-byte integer cannot be stored in a signed short, Java's
short
.
data
- the data block from which to readpos
- the starting index of data
to read from
-1
if fewer than two bytes exist
at that indexwriteUShort(java.io.OutputStream, int)
,
getUShort(int)
public static short getUByte(ByteBlock data, int pos)
pos
. If there is no byte at pos
,
-1
is returned.
short
because all values of
an unsigned one-byte integer cannot be stored in a signed byte, Java's
byte
.
data
- the data block to read frompos
- the index in data
of the byte to read
-1
if there is no byte at
that index (that is, if data.getLength() <= pos
)writeUByte(java.io.OutputStream, int)
,
getUByte(int)
public static java.net.Inet4Address getIPFromBytes(ByteBlock data, int pos)
pos
. If fewer than four bytes exist at the given
position, null
is returned.
InetAddress.getByAddress(byte[])
(that is, it calls it :) and is only
provided for convenience.
data
- the data block to read frompos
- the starting index of the IP address block in
data
null
if fewer than
four bytes exist at the given indexInetAddress.getByAddress(byte[])
,
Inet4Address.getAddress()
public static java.lang.String describeData(ByteBlock data)
data
contained { 0, 138, -118, -101
}
.
data
- the data block to describe
public static void writeLong(java.io.OutputStream out, long number) throws java.io.IOException
long
to the given stream.
The value is written as an eight-byte signed integer.
out
- the stream to write tonumber
- the value to write to the stream in binary format
java.io.IOException
- if an I/O error occursgetLong(long)
,
getLong(ByteBlock, int)
public static void writeUInt(java.io.OutputStream out, long number) throws java.io.IOException
out
- the stream to write tonumber
- the value to write to the stream in binary format
java.io.IOException
- if an I/O error occursgetUInt(long)
,
getUInt(ByteBlock, int)
public static void writeUShort(java.io.OutputStream out, int number) throws java.io.IOException
out
- the stream to write tonumber
- the value to write to the stream in binary format
java.io.IOException
- if an I/O error occursgetUShort(int)
,
getUShort(ByteBlock, int)
public static void writeUByte(java.io.OutputStream out, int number) throws java.io.IOException
out
- the stream to write tonumber
- the value to write to the stream in binary format
java.io.IOException
- if an I/O error occursgetUByte(int)
,
getUByte(ByteBlock, int)
public static byte[] getLong(long number)
long
in binary format.
number
- the value to be written to the returned array
writeLong(java.io.OutputStream, long)
,
getLong(ByteBlock, int)
public static byte[] getUInt(long number)
number
- the value to be written to the returned array
writeUInt(java.io.OutputStream, long)
,
getUInt(ByteBlock, int)
public static byte[] getUShort(int number)
number
- the value to be written to the returned array
writeUShort(java.io.OutputStream, int)
,
getUShort(ByteBlock, int)
public static byte[] getUByte(int number)
number
- the value to be written to the returned array
writeUByte(java.io.OutputStream, int)
,
getUByte(ByteBlock, int)
public static byte[] getAsciiBytes(java.lang.String string)
char[]
or char*
in C/C++ to a
stream.
string
- the string to be encoded in the returned array
getAsciiString(net.kano.joscar.ByteBlock)
,
String.getBytes(String)
public static java.lang.String getAsciiString(ByteBlock data)
String
representing the given block of ASCII
characters.
char[]
or char*
in C/C++ from a
stream.
data
- the block of ASCII characters
getAsciiBytes(java.lang.String)
,
String.String(byte[], String)
public static StringBlock getNullPadded(ByteBlock block)
StringBlock
contains an ASCII string formed from
all of the bytes in the given block before the first null byte
(0x00
) or the end of the block. Note that the
totalSize
field of the returned StringBlock
is
the length of the string without the null byte. This is to avoid
confusion when reading strings padded with more than one null byte or
those not padded at all (that is, when the block consists only of an
ASCII string with no null bytes).
block
- a block of data containing an ASCII string followed by zero
or more null (0x00
) bytes
StringBlock
containing the string extracted from
the given block and the size of the string without the null
byte(s) extracted, in bytesgetAsciiString(net.kano.joscar.ByteBlock)
public static void writeNullPadded(java.io.OutputStream out, ByteBlock block, int len) throws java.io.IOException
0x00
). This method is guaranteed to write
exactly len
bytes to the given stream, only writing the
first len
bytes of the given block (and no null bytes) if
block.getLength() > len
.
out
- a stream to which to writeblock
- the block to write to the given streamlen
- the total number of bytes to write to the given stream
java.io.IOException
- if an I/O error occurs
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |