net.kano.joscar.rvcmd.addins
Class AddinsReqRvCmd

java.lang.Object
  extended byRvCommand
      extended byAbstractRvCmd
          extended byAbstractRequestRvCmd
              extended byAddinsReqRvCmd

public class AddinsReqRvCmd
extends AbstractRequestRvCmd

A rendezvous command used to invite a user to use a specified add-in. For example, AOL Instant Messenger for Windows uses this command invite a user to play MS Hearts and Quake II.

An add-in invitation contains several fields, including a URI that describes the add-in (in case the recipient does not have that add-in), a sixteen-byte "UUID" block supposedly unique to that add-in type, an add-in name, and the sender's Windows network name (like \\NETWORKNAME).

Note: for information on the format of the URI, see the getAddinUri documentation.


Field Summary
static int CODE_DEFAULT
          The "code" value that is always sent by WinAIM.
static long FLAGS_DEFAULT
          The "flags" value that is always sent by WinAIM.
 
Fields inherited from class AbstractRequestRvCmd
FPRESENT_DEFAULT, REQTYPE_INITIALREQUEST, REQTYPE_REDIRECT
 
Fields inherited from class RvCommand
RVSTATUS_ACCEPT, RVSTATUS_DENY, RVSTATUS_REQUEST
 
Constructor Summary
AddinsReqRvCmd(int code, java.lang.String addinUri, ByteBlock uuid, java.lang.String addinName, java.lang.String computerName, long flags, InvitationMessage invMessage)
          Creates a new outgoing addins invitation request RV command with the given properties.
AddinsReqRvCmd(RecvRvIcbm icbm)
          Creates a new addins invitation command from the given incoming addins request RV ICBM.
 
Method Summary
 java.lang.String getAddinName()
          Returns the name of the associated add-in type.
 java.lang.String getAddinUri()
          Returns a URI that describes the associated add-in type, or null if none was sent.
 ByteBlock getAddinUuid()
          Returns the add-in unique ID ("UUID") block associated with the associated addin type, or null if none was sent.
 int getCode()
          Returns a "code" sent in this command.
 java.lang.String getComputerName()
          Returns the Windows network name of the sender.
 long getFlags()
          Returns a set of "flags" sent in this add-ins invitation.
protected  boolean hasServiceData()
          Returns whether this RV command's TLV list should contain a "service data block" TLV.
 java.lang.String toString()
           
protected  void writeRvTlvs(java.io.OutputStream out)
          Writes this RV command's list of rendezvous TLV's to the given stream.
protected  void writeServiceData(java.io.OutputStream out)
          Writes this RV command's "service data block."
 
Methods inherited from class AbstractRequestRvCmd
getRequestType, isFPresent, writeHeaderRvTlvs
 
Methods inherited from class AbstractRvCmd
getRvTlvs, getServiceData, writeRvData
 
Methods inherited from class RvCommand
getCapabilityBlock, getRvStatus
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

CODE_DEFAULT

public static final int CODE_DEFAULT
The "code" value that is always sent by WinAIM.

See Also:
Constant Field Values

FLAGS_DEFAULT

public static final long FLAGS_DEFAULT
The "flags" value that is always sent by WinAIM.

See Also:
Constant Field Values
Constructor Detail

AddinsReqRvCmd

public AddinsReqRvCmd(RecvRvIcbm icbm)
Creates a new addins invitation command from the given incoming addins request RV ICBM.

Parameters:
icbm - an incoming add-in request rendezvous ICBM command

AddinsReqRvCmd

public AddinsReqRvCmd(int code,
                      java.lang.String addinUri,
                      ByteBlock uuid,
                      java.lang.String addinName,
                      java.lang.String computerName,
                      long flags,
                      InvitationMessage invMessage)
Creates a new outgoing addins invitation request RV command with the given properties. Note that all values can be either null or -1 (depending on the argument's type, obviously) to indicate that that field sholdn't be sent in this invitation command.

Parameters:
code - a "code" for this invitation; normally CODE_DEFAULT
addinUri - a URI describing the type of add-in to which the recipient is being invited (see getAddinUri() for details)
uuid - a sixteen-byte block of data unique to the associated add-in type
addinName - the name of the associated add-in, like "MSHearts" or "QuakeII"
computerName - the Windows network name of the sender, like COMPUTERNAME in the network filename \\COMPUTERNAME\FILE.HTML"
flags - a set of flags to send; normally FLAGS_DEFAULT
invMessage - a message to send with this invitation
Method Detail

getCode

public final int getCode()
Returns a "code" sent in this command. As of this writing, this value is always CODE_DEFAULT (0) and its significance is unknown.

Returns:
a mysterious "code" send in this command, or -1 if none was sent

getAddinUri

public final java.lang.String getAddinUri()
Returns a URI that describes the associated add-in type, or null if none was sent.

Below is a typical URI sent by WinAIM:
 aim:AddGame?name=MSHearts&go1st=true&multiplayer=true&url=http://ww
 w.microsoft.com&cmd=%25m&servercmd=%20&hint=Both%20machines%20must%
 20be%20running%20Win95%3CBR%3Eor%20Win98%20and%20be%20on%20the%20sa
 me%20local%20network.%3CBR%3EWhen%20you%20send%20invite,%20choose%2
 0'I%20want%20to%20be%3CBR%3Edealer'%20and%20click%20on%20OK%20*befo
 re*%20buddy%3CBR%3Eresponds%20(so%20act%20fast).%20*After*%20buddy%
 3CBR%3Eresponds,%20press%20F2%20to%20start%20game.
 
After decoding with the Java API's URLDecoder and then parsing a bit more this becomes:
NameValue
nameMSHearts
go1sttrue
multiplayertrue
urlhttp://www.microsoft.com
cmd%m
servercmd[a single space]
hint Both machines must be running Win95<BR>
or Win98 and be on the same local network.<BR>
When you send invite, choose 'I want to be<BR>
dealer' and click on OK *before* buddy<BR>
responds (so act fast). *After* buddy<BR>
responds, press F2 to start game.

Returns:
an "addin URI" that describes the associated add-in, or null if none was sent

getAddinUuid

public final ByteBlock getAddinUuid()
Returns the add-in unique ID ("UUID") block associated with the associated addin type, or null if none was sent.

Returns:
the "UUID" of the associated add-in type

getAddinName

public final java.lang.String getAddinName()
Returns the name of the associated add-in type. This will be a string like "MSHearts" and "QuakeII" that may be used to uniquely identify an add-in.

Returns:
the name of the associated add-in

getComputerName

public final java.lang.String getComputerName()
Returns the Windows network name of the sender. This will be a name like COMPUTERNAME in the network pathname \\COMPUTERNAME\FILE.HTML.

Returns:
the sender's Windows network name

getFlags

public final long getFlags()
Returns a set of "flags" sent in this add-ins invitation. As of this writing, WinAIM always sends FLAGS_DEFAULT (0).

Returns:
the set of bit flags sent in this command

writeRvTlvs

protected void writeRvTlvs(java.io.OutputStream out)
                    throws java.io.IOException
Description copied from class: AbstractRvCmd
Writes this RV command's list of rendezvous TLV's to the given stream.

Specified by:
writeRvTlvs in class AbstractRvCmd
Parameters:
out - the stream to which to write
Throws:
java.io.IOException - if an I/O error occurs

hasServiceData

protected boolean hasServiceData()
Description copied from class: AbstractRvCmd
Returns whether this RV command's TLV list should contain a "service data block" TLV. The return value of this method must be consistent throughout this object's existence. Note that if this method returns false for an object, writeServiceData will never be called on that object. The default implementation of this method returns true.

Overrides:
hasServiceData in class AbstractRvCmd
Returns:
whether or not this RV command has a "service data block"
See Also:
AbstractRvCmd.writeServiceData(java.io.OutputStream)

writeServiceData

protected void writeServiceData(java.io.OutputStream out)
                         throws java.io.IOException
Description copied from class: AbstractRvCmd
Writes this RV command's "service data block." A service data block's format changes from rendezvous to rendezvous, but generally provides information specific to the type of rendezvous being sent. For example, in a file transfer request, the file's name and size (among other fields) are sent in the service block. This method will never be called if AbstractRvCmd.hasServiceData() returns false. The default implementation of this method does not write any data to the stream.

Overrides:
writeServiceData in class AbstractRvCmd
Parameters:
out - the stream to which to write
Throws:
java.io.IOException - if an I/O error occurs

toString

public java.lang.String toString()