wyvern.common.net
Interface RemoteClient

All Superinterfaces:
RemoteInventory, RemoteMap, RemoteStats, RPCConstants

public interface RemoteClient
extends RemoteMap, RemoteInventory, RemoteStats, RPCConstants

RPC interface for the client. The server makes calls through this interface to communicate with a client.

Version:
1.0, Apr 20, 1998
Author:
Steve Yegge

Nested Class Summary
 
Nested classes inherited from class wyvern.common.net.RPCConstants
RPCConstants.ImageAlign, RPCConstants.ImageFlags, RPCConstants.ImageFormat, RPCConstants.OutputView, RPCConstants.TextStyle
 
Field Summary
 
Fields inherited from interface wyvern.common.net.RemoteInventory
GROUND, INVENTORY
 
Fields inherited from interface wyvern.common.net.RPCConstants
ALERT_EVENT, CHAR_BANISHED, CHAR_BANNED, CHARACTER_NOT_FOUND, CLIENT_END_MUSIC_COMMAND, CLIENT_END_SOUND_COMMAND, CONNECT_RESULT, FLUSH_GRAPHICS, GND_ADD, GND_MODIFY, GND_REMOVE, GND_RESEND, INV_ADD, INV_MODIFY, INV_REMOVE, INV_RESEND, INVALID_PASSWORD, IP_BANISHED, LOGIN_FAILURE, LOGIN_SUCCESS, LOGINS_DISABLED, MAX_IMAGE_SIZE, MUSIC_EVENT, OTHER_LOGIN_ERROR, PAUSE_SOUND, PLAY_ALERT, PLAY_MUSIC, PLAY_SOUND, PROTOCOL_VERSION_MAJOR, PROTOCOL_VERSION_MINOR, QUIT, REGISTER_EXISTING_PLAYER, RESUME_SOUND, SAME_EMAIL_ONLINE, SEND_FILE, SEND_IMAGE, SEND_PICTURE, SEND_TILE, SEND_TILE_MAPPINGS, SERVER_TRANSFER, SET_GAIN, SOUND_EVENT, STAT_SEND_SPELLS, STAT_SET_FOOD, STAT_SET_GOLD, STAT_SET_HP, STAT_SET_LEVEL, STAT_SET_LOAD, STAT_SET_NAME, STAT_SET_RANGE, STAT_SET_SP, STAT_SET_XP, STAT_START_POISON, STAT_STOP_POISON, STAT_UPDATE_ALL, STOP_ALL_SOUNDS, STOP_MUSIC, STOP_SOUND, TEXT_OUT, TOO_MANY_PLAYERS, UNCACHE_IMAGE, XML_COMMAND, XML_COMMAND_WITH_COMPRESSED_DATA, XML_COMMAND_WITH_DATA, ZIP_PARTIAL_SCREEN, ZIP_SCREEN, ZIP_TEXT_OUT
 
Method Summary
 java.lang.String getHostAddress()
          Returns the IP address this socket is connected to.
 java.lang.String getIP()
          Returns the IP address for the associated Player.
 int getMajorVersion()
           
 int getMinorVersion()
          Returns the major version number of this client.
 java.lang.String getName()
          Returns the name of the player we're associated with.
 Player getPlayer()
          Returns the Player associated with this client.
 int getReleaseVersion()
          Returns the major version number of this client.
 RPCVersion getRPCVersion()
          Gets the protocol version for this client.
 wyvern.server.IClientSession getSession()
          Returns the ClientSession we're paired with (we do the output, it does the input).
 java.net.Socket getSocket()
          Returns the TCP Socket for this client.
 java.lang.String getVersionString()
          Returns the entire version string for this client.
 boolean isHandheld()
          Returns true if this is a handheld client.
 boolean isRobot()
          Used for automated testing scripts.
 boolean isShutDown()
          Returns true if the client has been told to shut down, e.g. from an IOException, or because the player quit normally.
 boolean isTelnet()
          Returns true if this is a telnet client.
 void pauseSound(java.lang.String id)
          Pauses a particular sound.
 void playAlert(java.lang.String path)
          Plays the specified sound file on the client, one repeat, no delay, and the default gain.
 void playAlert(java.lang.String path, int repeats, int repeatDelay, double gain)
          Plays the specified alert with custom parameters.
 void playMusic(java.lang.String path, java.lang.String id)
          Sets the background music track to the specified file, with the default gain/volume.
 void playMusic(java.lang.String path, java.lang.String id, int repeats, int repeatDelay, double gain)
          Plays the specified music with custom parameters.
 void playSound(java.lang.String path, java.lang.String id)
          Plays a sound effect on the client with the default gain.
 void playSound(java.lang.String path, java.lang.String id, int repeats, int repeatDelay, double gain)
          Plays the specified sound effect with custom parameters.
 void quit()
          Tells the client that the player has been dumped off the game.
 void resumeSound(java.lang.String id)
          Resumes a particular sound.
 void sendFile(java.lang.String path, java.lang.String command)
          Sends a file to the client, requested by a #download command.
 void sendHandshake(boolean success, java.lang.String msg)
          Acknowledges registration with a success or failure code.
 void sendImage(java.lang.String path)
          Sends an image file to the client.
 void sendPicture(java.lang.String path, java.lang.String title, byte format, byte align, byte view, int flags)
          Sends a picture to be displayed in the text-display area, or in a popup.
 void sendTile(int tile, java.lang.String path, long timestamp)
          Sends a tile-number-to-image mapping to the client.
 void sendTileMappings()
          Sends the tile/image mappings that have been generated on the server since the server started up.
 void serverTransfer(java.lang.String host)
          Instructs the player to connect to the specified server.
 void setHandheld(boolean handheld)
          Flags this as a handheld client.
 void setMusicGain(double gain)
          Sets the volume of the background music.
 void setPlayer(Player player)
          Sets the Player object for this RemoteClient.
 void setRPCVersion(RPCVersion v)
          Sets the protocol version for this client.
 void setSoundGain(java.lang.String id, double gain)
          Sets the volume of a particular sound playing on the client.
 void shutDown()
          Shuts the client down.
 void stopAllSounds()
          Stops all of the currently playing sounds on the client.
 void stopMusic()
          Stops the background music completely.
 void stopSound(java.lang.String id)
          Stops the specified sound effect.
 void textOut(java.lang.String text)
          Outputs some text to the client text display area, using the default style.
 void textOut(java.lang.String[] pieces, byte[] styles)
          Outputs a message to the client text display area.
 void textOut(java.lang.String text, byte style)
          Outputs some text to the client text display area.
 void textOut(java.lang.String text, java.lang.String font, int rgba, int size)
          Outputs some text to the client text display area.
 void uncacheImage(java.lang.String path)
          Tells the client to uncache an image's data, which will force it to ask for a new copy.
 void writeByte(byte b)
          Writes a single byte to the output stream, usually one of the commands in RPCConstants.
 
Methods inherited from interface wyvern.common.net.RemoteMap
sendPartialScreen, sendZippedScreen
 
Methods inherited from interface wyvern.common.net.RemoteInventory
add, modify, remove, resend
 
Methods inherited from interface wyvern.common.net.RemoteStats
sendSpells, setFood, setGold, setHP, setLevel, setLoad, setName, setRange, setSP, setXP, startPoison, stopPoison, updateAll
 

Method Detail

writeByte

public void writeByte(byte b)
Writes a single byte to the output stream, usually one of the commands in RPCConstants. Byte is encoded in the packet header, with data length of zero.

Parameters:
b - the byte to write

textOut

public void textOut(java.lang.String text)
Outputs some text to the client text display area, using the default style.

Parameters:
text - text to display

textOut

public void textOut(java.lang.String text,
                    byte style)
Outputs some text to the client text display area.

Parameters:
text - text to display
style - an RPCConstants.TextStyle enum value

textOut

public void textOut(java.lang.String text,
                    java.lang.String font,
                    int rgba,
                    int size)
Outputs some text to the client text display area. (Not yet implemented)

Parameters:
text - the message to display
font - the font style ( "serif", "dialog", etc. - must be interpreted by the client, and the client may not support it.)
rgba - a 32-bit rgba value for the color
size - the font size (e.g. 10 for 10-point)

textOut

public void textOut(java.lang.String[] pieces,
                    byte[] styles)
Outputs a message to the client text display area. The message is split into pieces, so you can specify the predefined style to use for each piece.

Parameters:
pieces - a list of strings that will be joined together
styles - the RPCConstants.TextStyle for each piece The styles and pieces arrays must be the same length.

sendPicture

public void sendPicture(java.lang.String path,
                        java.lang.String title,
                        byte format,
                        byte align,
                        byte view,
                        int flags)
Sends a picture to be displayed in the text-display area, or in a popup.

Parameters:
path - the relative path to the image file
title - the title of the picture, to be displayed if the client doesn't support images, or if the image couldn't be loaded
align - an RPCConstants.ImageAlign constant
format - an RPCConstants.ImageFormat constant
view - an RPCConstants.OutputView constant
flags - RPCConstants.ImageFlags

sendFile

public void sendFile(java.lang.String path,
                     java.lang.String command)
Sends a file to the client, requested by a #download command.

Parameters:
path - the relative path to the file, including extension. Files without extensions cannot be sent.
command - the (entire) command that the client sent in order to request the file, e.g. "#download music/ogg/foo.ogg". The last argument to the command is the file path, and anything before it can be used for routing on the client side. E.g. "#download audio 12345 music/ogg/foo.ogg" will still request a file download of foo.ogg, but the client can get read the routing stuff out of the original command string when it comes back.

quit

public void quit()
Tells the client that the player has been dumped off the game.


sendHandshake

public void sendHandshake(boolean success,
                          java.lang.String msg)
Acknowledges registration with a success or failure code.

Parameters:
success - true if the player was registered
msg - the message to display if unsuccessful

serverTransfer

public void serverTransfer(java.lang.String host)
Instructs the player to connect to the specified server.

Parameters:
host - the host that's expecting this player to connect, e.g. "jade.cabochon.com"

sendTileMappings

public void sendTileMappings()
Sends the tile/image mappings that have been generated on the server since the server started up.


sendTile

public void sendTile(int tile,
                     java.lang.String path,
                     long timestamp)
Sends a tile-number-to-image mapping to the client.

Parameters:
tile - the tile number
path - the path to the image in the client's image cache
timestamp - the last time the image was modified

sendImage

public void sendImage(java.lang.String path)
Sends an image file to the client.

Parameters:
path - where to put the image in the client's image cache

uncacheImage

public void uncacheImage(java.lang.String path)
Tells the client to uncache an image's data, which will force it to ask for a new copy.

Parameters:
path - the (relative) image path to uncache

playAlert

public void playAlert(java.lang.String path)
Plays the specified sound file on the client, one repeat, no delay, and the default gain.

Can't be stopped, so use with care.

Parameters:
path - the relative path to the sound file

playAlert

public void playAlert(java.lang.String path,
                      int repeats,
                      int repeatDelay,
                      double gain)
Plays the specified alert with custom parameters. Can't be stopped, so use with care.

Parameters are file path, number of repeats, delay between repeats, and gain (volume). The alert won't play if the path is null or not found on the server. All other params are adjusted to be within the valid range for the parameter, if necessary.

Parameters:
path - the relative path to the sound file.
repeats - number of times the client should repeat the piece before stopping (and for music and sound, sending the notification back to the server). 0 means don't repeat; just play and stop.
repeatDelay - number of milliseconds to pause between repeats, if we're repeating.
gain - the volume for this track, from 0.0 to 1.0

playMusic

public void playMusic(java.lang.String path,
                      java.lang.String id)
Sets the background music track to the specified file, with the default gain/volume. The number of repeats and delay are client-dependent: some clients may choose to loop, and others may choose to play it once, or a few times. It may even be a user-configurable option.

Client sends an "#endmusic" directive back to the server when it's finished playing all the repeats. If the piece is looping indefinitely, it will not send the directive, even when the music is changed or stopped.

Parameters:
path - the relative path to the sound file, including extension. Can be any supported sound format (midi, ogg, others.) Nothing will be played if the path is null, or the file isn't found on the server.


playMusic

public void playMusic(java.lang.String path,
                      java.lang.String id,
                      int repeats,
                      int repeatDelay,
                      double gain)
Plays the specified music with custom parameters.

Parameters:
path - the relative path to the sound file. Can be any supported sound format.
repeats - number of times the client should repeat the piece before stopping and sending a notification back to the server. A value of 0 means don't repeat; just play the track once. A value of -1 means repeat indefinitely.
repeatDelay - number of milliseconds to pause between repeats, if we're repeating. Negative values are interpreted as zero (no delay).
gain - the volume for this track, from 0.0 to 1.0. Values outside the range are clipped to 0.0 or 1.0.

stopMusic

public void stopMusic()
Stops the background music completely. Client does not send a notification back to the server.


setMusicGain

public void setMusicGain(double gain)
Sets the volume of the background music.

Parameters:
gain - the new background music gain, from 0.0 to 1.0

playSound

public void playSound(java.lang.String path,
                      java.lang.String id)
Plays a sound effect on the client with the default gain. Plays the sound exactly once, with no delay.

Client sends a "#endsound id" directive back to the server when the sound finishes playing, unless it was interrupted with stopSound() or stopAllSounds().

Parameters:
path - relative path to the sound file, in any supported format, including midi.
id - the unique ID of this sound. It has to be unique, so you can't use (for example) the hashcode of the path to the file, since more than one of the same sound may be playing at once. Usually you pass the hashcode of the object that emitted the sound.

playSound

public void playSound(java.lang.String path,
                      java.lang.String id,
                      int repeats,
                      int repeatDelay,
                      double gain)
Plays the specified sound effect with custom parameters. Client sends a "#endsound id" directive back to the server when the sound finishes playing, unless it was interrupted with stopSound() or stopAllSounds().

Parameters:
path - the relative path to the sound file, in any supported format, including midi.
id - the unique ID of this sound. It has to be unique, so you can't use (for example) the hashcode of the path to the file, since more than one of the same sound may be playing at once. Usually you pass the hashcode of the object that emitted the sound.
repeats - number of times the client should repeat the piece before stopping and sending a notification back to the server. A value of 0 means don't repeat; just play the track once. A value of -1 means repeat indefinitely, until explicitly stopped.
repeatDelay - number of milliseconds to pause between repeats, if we're repeating. Negative values are interpreted as zero (no delay).
gain - the volume for this track, from 0.0 to 1.0. Values outside the range are clipped to 0.0 or 1.0.

stopSound

public void stopSound(java.lang.String id)
Stops the specified sound effect.

Parameters:
id - the unique ID of the sound effect. The client will not send an "#endsound" back to the server.

stopAllSounds

public void stopAllSounds()
Stops all of the currently playing sounds on the client. Does not stop the background music or any currently-playing alerts. No notifications are sent back from theclient.


setSoundGain

public void setSoundGain(java.lang.String id,
                         double gain)
Sets the volume of a particular sound playing on the client.

Parameters:
gain - the new background music gain, from 0.0 to 1.0
id - the unique track ID for the sound to modify

pauseSound

public void pauseSound(java.lang.String id)
Pauses a particular sound. The sound will stop playing on the client, and resume when we call resumeSound() with this track id. If the sound is stopped with stop() after pausing it, then it cannot be resumed, and will ignore the resumeSound() request.

Parameters:
id - the unique track id of the sound to resume

resumeSound

public void resumeSound(java.lang.String id)
Resumes a particular sound. The sound will resume on the client, unless it was stopped after it was paused.

Parameters:
id - the unique track id of the sound to resume

isTelnet

public boolean isTelnet()
Returns true if this is a telnet client. For local use only; there's no RPC call associated with it.

Returns:
true if the client we're managing is a telnet client

setPlayer

public void setPlayer(Player player)
Sets the Player object for this RemoteClient. For local use only.


getPlayer

public Player getPlayer()
Returns the Player associated with this client.


getName

public java.lang.String getName()
Returns the name of the player we're associated with.


getHostAddress

public java.lang.String getHostAddress()
Returns the IP address this socket is connected to.

Returns:
the IP address the player is connected from, or null if not connected/unavailable.

setHandheld

public void setHandheld(boolean handheld)
Flags this as a handheld client.


getSession

public wyvern.server.IClientSession getSession()
Returns the ClientSession we're paired with (we do the output, it does the input).


getSocket

public java.net.Socket getSocket()
Returns the TCP Socket for this client.


getIP

public java.lang.String getIP()
Returns the IP address for the associated Player.


isHandheld

public boolean isHandheld()
Returns true if this is a handheld client.

Returns:
true for PDAs, false for the web client and telnet.

shutDown

public void shutDown()
Shuts the client down. It won't send any more output. Normally you shouldn't call this - the networking code does it when the player goes net-dead.


isShutDown

public boolean isShutDown()
Returns true if the client has been told to shut down, e.g. from an IOException, or because the player quit normally.


getMajorVersion

public int getMajorVersion()

getMinorVersion

public int getMinorVersion()
Returns the major version number of this client.

Returns:
the major version. If the client version is "1.2.3", the minor version number is 2.

getReleaseVersion

public int getReleaseVersion()
Returns the major version number of this client.

Returns:
the major version. If the client version is "1.2.3", the release version number is 3.

getVersionString

public java.lang.String getVersionString()
Returns the entire version string for this client.

Returns:
version string passed in by the client, e.g. "1.2.3"

setRPCVersion

public void setRPCVersion(RPCVersion v)
Sets the protocol version for this client. Don't use.


getRPCVersion

public RPCVersion getRPCVersion()
Gets the protocol version for this client. Don't use.


isRobot

public boolean isRobot()
Used for automated testing scripts. Always false for players logged in normally.