com.SecurePlay
Interface SPGameAPIInterface

All Known Implementing Classes:

SPGameAPIClass

public interface SPGameAPIInterface

This is the GameAPI class interface

Author:

IT GlobalSecure Inc.

See Also:

SecurePlay License Information

Method Summary

boolean	APIAddListener(SPEventInterface gameobj) This method adds a listener object for Game API events
boolean	APIBcreateTransaction(java.lang.String transtype, java.lang.String transmaster, java.lang.String[] playerIDList, boolean privateflag) This method allows the creation of a new, internally controlled transaction.
boolean	APIbeginGame(java.lang.String playerID) This method safely begins the game
boolean	APIClearListeners() This method clears the listener objects for Game API events
boolean	APIcloseTransaction(java.lang.String transID) This method removes a transaction from the game instance's open transaction list.
SPTBlastClass	APIcreateBlastTransaction(java.lang.String pid, java.lang.String[] transcontent) This method creates a default Blast Transaction for this library.
SPAbstractTransactionInterface	APIcreateTransaction(java.lang.String transtype, java.lang.String transmaster, java.lang.String[] playerIDList, boolean privateflag) This method allows the creation of a new, internally controlled transaction.
boolean	APIendGame(java.lang.String playerID) This method safely ends a game.
SPLogInterface	APIgetGameLog() Gets the messagelog object from the gameinstance
java.lang.Object	APIgetGameLogCurrentEntry() Returns current entry from the messagelog object of comms
int	APIgetGameLogLength() returns the number entries in messagelog
java.lang.Object	APIgetGameLogNextEntry() Returns the next entry from the messagelog object of comms
java.lang.Object	APIgetGameLogPreviousEntry() Returns the previous entry from the messagelog object of the comms
java.lang.String	APIgetLicenseSummary() This method returns a summary of the licensee information for the current game instance.
int	APIGetListenerCount() This method returns the number of listener objects for Game API events
java.lang.Object[]	APIGetListeners() This method returns a list of listener objects for Game API events
java.lang.String[]	APIgetOpenTransactionIDs() Returns a vector that contains a list of open transaction IDs
SPPlayerInterface	APIgetPlayer(java.lang.String pid) This method gets the player from the game instance using the player ID
java.lang.String[]	APIgetPlayerIDList() This method gets the player id list list associated with this game.
SPAbstractTransactionInterface	APIgetTransaction(java.lang.String tid) This method gets the transaction from the game instance using the transaction ID
SPAbstractTransactionAPIInterface	APIgetTransactionAPI(java.lang.String tid) This method returns the transaction API of the game transaction using sid.
boolean	APIPlayerJoin(java.lang.String sender, java.lang.String pid, java.lang.String cid) This method allows the Game instance Master to safely add a new player during the course of a game and to notify the remote players of this information.
boolean	APIPlayerJoin(java.lang.String sender, java.lang.String pid, java.lang.String cid, boolean rflag) This method allows the Game instance Master to safely add a new player during the course of a game and to notify the remote players of this information.
boolean	APIRemoveListener(SPEventInterface gameobj) This method removes a listener object for Game API events
boolean	APIrequestbeginGame(java.lang.String playerID) This method sends a request to the game instance master to begin the game.
boolean	APIrequestcreateTransaction(java.lang.String pid, java.lang.String transmaster, java.lang.String transtype, java.lang.String[] playerIDList, boolean privateflagIN) This method safely allows a player to request the creation of a new transaction of a given type and parameters.
boolean	APIrequestendGame(java.lang.String playerID) This method sends a message from the specified player to the game instance master to end the game.
boolean	APIrequestPlayerJoin(java.lang.String sender, java.lang.String pid, java.lang.String cid, boolean rflagIN) This method sends a request to a remote game instance to add a player during a game.
SPAbstractTransactionAPIInterface	APITAOcreateTransaction(java.lang.String transtype, java.lang.String transmaster, java.lang.String[] playerIDList, boolean privateflag) This method allows the creation of a new, internally controlled transaction.
SPGameClass	getGameinstance() Getter function that returns the property: gameinstance
java.lang.String	GetNextGameSegmentID(java.lang.String currentsegment) This method gets automatically called by the Game any time the conditions for a new Game Segment are met according to the SecurePlay Library license.
boolean	isPlayerIncluded(java.lang.String pid) This method tests to determine if a specified player is a transaction participant.
boolean	isPlayerInternal(java.lang.String pid) This method checks to see whether a specified playerID is internal to the local SecurePlay library process
boolean	joinPlayer(java.lang.String pid, java.lang.String cid, boolean rflag) This method carries out the local process of adding a new Player to the local game instance.
void	onBlast(SPMessageClass messObj) This method handles incoming new Blast Transactions
void	onnewGameBlock(SPMessageClass messObj) This method handles incoming new Game Blocks
boolean	onnewTransaction(SPMessageClass incoming) This method handles messages for new incoming transactions.
boolean	onPlayerJoin(SPMessageClass messObj) This method safely handles remote messages for the addition of a player to the local game instance.
boolean	onrequestcreateTransaction(SPMessageClass incoming) This method handles incoming requests for the creation of new transactions.
boolean	onrequestPlayerJoin(SPMessageClass messObj) Safely handles requests to add a player.
boolean	rulesbeginGame(java.lang.String requesterID) This is a shell function to allow the insertion of rules code for the decision to begin a game.
boolean	rulescreateTransaction(java.lang.String sender, java.lang.String transtype, java.lang.String master, java.lang.String[] players, boolean pflag) This method safely allows a player to request the creation of a new transaction of a given type and parameters.
boolean	rulesendGame(java.lang.String requesterID) This is a shell method to allow the evaluation of the game rules to determine if the game should be allowed to end.
boolean	rulesnewplayerconfig(java.lang.String pid, java.lang.String cid, boolean rflag) This shell method takes an incoming proposed configuration for a new player and maps it against the local preference for that player, if different.
boolean	rulesPlayerJoin(java.lang.String sender, java.lang.String[] messbody) This is a shell method to determine if a player will be allowed to join in midgame.
boolean	sendMessage(java.lang.String sender, java.lang.String[] receivers, boolean encryptflag, boolean privateflag, java.lang.String messagetype, java.lang.String[] messagebody, java.lang.String[] altmessage) This method is a wrapper for the game instance sendMessage() method.

Method Detail

APIbeginGame

public boolean APIbeginGame(java.lang.String playerID)

This method safely begins the game

Parameters:

playerID - String - player id is the master.

Returns:

result - Boolean: TRUE- if successful, FALSE, if not

APIendGame

public boolean APIendGame(java.lang.String playerID)

This method safely ends a game.

Parameters:

playerID - String - player id is the master.

Returns:

result - Boolean: TRUE, if successful, FALSE, if not.

GetNextGameSegmentID

public java.lang.String GetNextGameSegmentID(java.lang.String currentsegment)

This method gets automatically called by the Game any time the conditions for a new Game Segment are met according to the SecurePlay Library license. THIS FUNCTION IS A STUB - A global system for unique game segment generation needs to be created in compliance with the SecurePlay license. NOTE - An initial Game Segment needs to be set for each individual game played online this is highly variable - it could be set by a server, a client, a peer, or other system on a case-by-case basis. The base Game Segment ID is provided by SecurePlay.com. One party to the game or supporting the game is responsible for setting the Game Segment ID - the master for the game transaction in this reference implementation. REMOVAL, CIRCUMVENTION, OR DELETION OF THIS FUNCTION IS A VIOLATION OF THE SECUREPLAY LICENSE. ANY CHANGES MUST BE COORDINATED - SEE THE SECUREPLAY LICENSE FOR DETAILS.

Parameters:

currentsegment - String - current game segment, but currently not used because the method is a shell.

Returns:

gameSegment - String - new game segement ID

isPlayerInternal

public boolean isPlayerInternal(java.lang.String pid)

This method checks to see whether a specified playerID is internal to the local SecurePlay library process

Parameters:

pid - String - player id to be checked.

Returns:

result - Boolean: TRUE, if internal, FALSE, if not

isPlayerIncluded

public boolean isPlayerIncluded(java.lang.String pid)

This method tests to determine if a specified player is a transaction participant.

Parameters:

pid - String - player id to be checked.

Returns:

result - Boolean: TRUE, if internal, FALSE, if not

APIcloseTransaction

public boolean APIcloseTransaction(java.lang.String transID)

This method removes a transaction from the game instance's open transaction list.

Parameters:

transID - String - transaction id to beremoved.

Returns:

result - Boolean: TRUE, if successful, FALSE, if not.

APIcreateTransaction

public SPAbstractTransactionInterface APIcreateTransaction(java.lang.String transtype,
                                                           java.lang.String transmaster,
                                                           java.lang.String[] playerIDList,
                                                           boolean privateflag)

This method allows the creation of a new, internally controlled transaction. It also sends a message to the other transaction and game participants about this new transaction. NOTE: Thims method may not be supported

Parameters:

transtype - String - specified transaction type

transmaster - String - player id of the master of the transaction

playerIDList - String[] - This is an array that holds the Player IDs of the players within the game that are participating in this transaction.

privateflag - boolean - This is a flag to describe whether the specific transaction is a private transaction to the non-participating Players.

Returns:

tran - SPAbstractTransactionInterface(but returns the actual object) - if successful, null if not

APIcreateBlastTransaction

public SPTBlastClass APIcreateBlastTransaction(java.lang.String pid,
                                               java.lang.String[] transcontent)

This method creates a default Blast Transaction for this library.

Parameters:

pid - String - player id.

transcontent - String[] - content of this transaction.

Returns:

SPTBlastClass - pointer to the created transaction.

APIBcreateTransaction

public boolean APIBcreateTransaction(java.lang.String transtype,
                                     java.lang.String transmaster,
                                     java.lang.String[] playerIDList,
                                     boolean privateflag)

This method allows the creation of a new, internally controlled transaction. It also sends a message to the other transaction and game participants about this new transaction. NOTE: Thims method may not be supported

Parameters:

transtype - String - specified transaction type

transmaster - String - player id of the master of the transaction

playerIDList - String[] - This is an array that holds the Player IDs of the players within the game that are participating in this transaction.

privateflag - boolean - This is a flag to describe whether the specific transaction is a private transaction to the non-participating Players.

Returns:

result - Boolean: TRUE, if successful, FALSE, if not.

APITAOcreateTransaction

public SPAbstractTransactionAPIInterface APITAOcreateTransaction(java.lang.String transtype,
                                                                 java.lang.String transmaster,
                                                                 java.lang.String[] playerIDList,
                                                                 boolean privateflag)

This method allows the creation of a new, internally controlled transaction. It also sends a message to the other transaction and game participants about this new transaction. NOTE: Thims method may not be supported

Parameters:

transtype - String - specified transaction type

transmaster - String - player id of the master of the transaction

playerIDList - String[] - This is an array that holds the Player IDs of the players within the game that are participating in this transaction.

privateflag - boolean - This is a flag to describe whether the specific transaction is a private transaction to the non-participating Players.

Returns:

tran - SPAbstractTransactionAPIInterface - if successful, null if not

onnewTransaction

public boolean onnewTransaction(SPMessageClass incoming)

This method handles messages for new incoming transactions. It ensures that the new transactions are safely instantiated and loaed into the game.

Parameters:

incoming - SPMessageClass - the incoming message.

Returns:

result - Boolean: TRUE, if successful, FALSE, if not

APIPlayerJoin

public boolean APIPlayerJoin(java.lang.String sender,
                             java.lang.String pid,
                             java.lang.String cid)

This method allows the Game instance Master to safely add a new player during the course of a game and to notify the remote players of this information.

Parameters:

sender - String - player id of the sender

pid - String - player id to be joined

cid - String - comms id to be used

Returns:

result - Boolean: TRUE, if successful, FALSE, if not

APIPlayerJoin

public boolean APIPlayerJoin(java.lang.String sender,
                             java.lang.String pid,
                             java.lang.String cid,
                             boolean rflag)

This method allows the Game instance Master to safely add a new player during the course of a game and to notify the remote players of this information. This method will not be supported in the next version of the library.

Parameters:

sender - String - player id of the sender

pid - String - player id to be joined

cid - String - comms id to be used

rflag - boolean - relay flag

Returns:

result - Boolean: TRUE, if successful, FALSE, if not

onPlayerJoin

public boolean onPlayerJoin(SPMessageClass messObj)

This method safely handles remote messages for the addition of a player to the local game instance.

Parameters:

messObj - SPMessageClass - incoming Message Object

Returns:

result - Boolean: TRUE, if successful, FALSE, if not.

joinPlayer

public boolean joinPlayer(java.lang.String pid,
                          java.lang.String cid,
                          boolean rflag)

This method carries out the local process of adding a new Player to the local game instance.

Parameters:

pid - String - player id to be joined

cid - String - comms id to used

rflag - boolean - relay flag

Returns:

result - Boolean: TRUE, if successful, FALSE, if not

APIrequestbeginGame

public boolean APIrequestbeginGame(java.lang.String playerID)

This method sends a request to the game instance master to begin the game.

Parameters:

playerID - String - id of player who is requesting

Returns:

result - Boolean: TRUE, if successful, FALSE, if not.

APIrequestendGame

public boolean APIrequestendGame(java.lang.String playerID)

This method sends a message from the specified player to the game instance master to end the game.

Parameters:

playerID - String - id of the player requesting

Returns:

result - Boolean: TRUE, if successful, FALSE, if not

APIrequestcreateTransaction

public boolean APIrequestcreateTransaction(java.lang.String pid,
                                           java.lang.String transmaster,
                                           java.lang.String transtype,
                                           java.lang.String[] playerIDList,
                                           boolean privateflagIN)

This method safely allows a player to request the creation of a new transaction of a given type and parameters.

Parameters:

pid - String - player id of the player who is requesting (cannot be the master)

transmaster - String - player id of the master.

transtype - String - transaction type to be created

playerIDList - String[] - This is an array that holds the Player IDs of the players within the game that are participating in this transaction.

privateflagIN - boolean - This is a flag to describe whether the specific transaction is a private transaction to the non-participating Players.

Returns:

result - Boolean: TRUE, if request sent successfully, FALSE, if not

APIrequestPlayerJoin

public boolean APIrequestPlayerJoin(java.lang.String sender,
                                    java.lang.String pid,
                                    java.lang.String cid,
                                    boolean rflagIN)

This method sends a request to a remote game instance to add a player during a game. Note, only the game master can add a player.

Parameters:

sender - String - player id of the player who is requesting (can not be the master).

pid - String - player id of the master.

cid - String - comms id.

rflagIN - boolean - relay flag

Returns:

result - Boolean: TRUE, if request successfully sent, FALSE, if not.

onrequestcreateTransaction

public boolean onrequestcreateTransaction(SPMessageClass incoming)

This method handles incoming requests for the creation of new transactions. Only the proposed transaction master can create a new transaction.

Parameters:

incoming - SPMessageClass - incoming message

Returns:

Boolean - TRUE, if successful, FALSE, if not.

onrequestPlayerJoin

public boolean onrequestPlayerJoin(SPMessageClass messObj)

Safely handles requests to add a player. Only the Game Master can add a player.

Parameters:

messObj - SPMessageClass - incoming Message Object

Returns:

Boolean - TRUE, if successful, FALSE, if not.

APIgetLicenseSummary

public java.lang.String APIgetLicenseSummary()

This method returns a summary of the licensee information for the current game instance. This information needs to be publicly available from any game instance, see SecurePlay license for details.

Returns:

fulllicensetext - String - this string contains full license information.

APIgetGameLog

public SPLogInterface APIgetGameLog()

Gets the messagelog object from the gameinstance

Returns:

messlog - SPLogInterface - this object contains the message logs of the game instance.

APIgetGameLogCurrentEntry

public java.lang.Object APIgetGameLogCurrentEntry()

Returns current entry from the messagelog object of comms

Returns:

messEntry - Object - this is the current entry in the message log

APIgetGameLogLength

public int APIgetGameLogLength()

returns the number entries in messagelog

Returns:

length - int - this is the length or number of messages in the game message log object.

APIgetGameLogNextEntry

public java.lang.Object APIgetGameLogNextEntry()

Returns the next entry from the messagelog object of comms

Returns:

messEntry - Object - this is the next entry in the message log

APIgetGameLogPreviousEntry

public java.lang.Object APIgetGameLogPreviousEntry()

Returns the previous entry from the messagelog object of the comms

Returns:

messEntry - Object - this is the previous entry in the message log

APIgetOpenTransactionIDs

public java.lang.String[] APIgetOpenTransactionIDs()

Returns a vector that contains a list of open transaction IDs

Returns:

v - Vector - the list of open transaction ids.

APIgetTransactionAPI

public SPAbstractTransactionAPIInterface APIgetTransactionAPI(java.lang.String tid)

This method returns the transaction API of the game transaction using sid.

Parameters:

tid - String - the transaction id.

Returns:

tranAPI - SPAbstractTransactionAPIInterface - the transaction API.

sendMessage

public boolean sendMessage(java.lang.String sender,
                           java.lang.String[] receivers,
                           boolean encryptflag,
                           boolean privateflag,
                           java.lang.String messagetype,
                           java.lang.String[] messagebody,
                           java.lang.String[] altmessage)

This method is a wrapper for the game instance sendMessage() method.

Parameters:

sender - - id of the sender

receivers - - ids of the recievers of the message

encryptflag - - encryption flag

privateflag - - private flag

messagetype - - the type of message

messagebody - - the message body

altmessage - - alternative message

Returns:

Boolean - TRUE, if successful, FALSE, if not

APIgetTransaction

public SPAbstractTransactionInterface APIgetTransaction(java.lang.String tid)

This method gets the transaction from the game instance using the transaction ID

Parameters:

tid - String - the transaction id

Returns:

tran - SPAbstractTransactionInterface(actual transaction obj) - the transaction from the game instance.

APIAddListener

public boolean APIAddListener(SPEventInterface gameobj)

This method adds a listener object for Game API events

Parameters:

gameobj - SPEventInterface - the object to be added, that inplement the listener interface

Returns:

Boolean - TRUE, if successful, FALSE, if not

See Also:

SPRootTransactionClass.APIAddListener(SPEventInterface gameobj)

APIRemoveListener

public boolean APIRemoveListener(SPEventInterface gameobj)

This method removes a listener object for Game API events

Parameters:

gameobj - SPEventInterface - the object to be removed, that inplement the listener interface

Returns:

Boolean - TRUE, if successful, FALSE, if not

See Also:

SPRootTransactionClass.APIRemoveListener(SPEventInterface gameobj)

APIGetListeners

public java.lang.Object[] APIGetListeners()

This method returns a list of listener objects for Game API events

Returns:

obj - Object[] - array of listener objects

See Also:

SPRootTransactionClass.APIGetListeners()

APIClearListeners

public boolean APIClearListeners()

This method clears the listener objects for Game API events

Returns:

Boolean - TRUE, if successful, FALSE, if not

See Also:

SPRootTransactionClass.APIClearListeners()

APIGetListenerCount

public int APIGetListenerCount()

This method returns the number of listener objects for Game API events

Returns:

count - int - the number of listeners

See Also:

SPRootTransactionClass.APIGetListenerCount()

APIgetPlayer

public SPPlayerInterface APIgetPlayer(java.lang.String pid)

This method gets the player from the game instance using the player ID

Parameters:

pid - String - the player ID

Returns:

player - SPPlayerInterface(actual player obj) - the player from the game instance.

APIgetPlayerIDList

public java.lang.String[] APIgetPlayerIDList()

This method gets the player id list list associated with this game.

Returns:

String[] - player id list.

rulesbeginGame

public boolean rulesbeginGame(java.lang.String requesterID)

This is a shell function to allow the insertion of rules code for the decision to begin a game.

Parameters:

requesterID - String - the id of the player who requested the request.

Returns:

Boolean - TRUE, if successful, FALSE, if not

rulesendGame

public boolean rulesendGame(java.lang.String requesterID)

This is a shell method to allow the evaluation of the game rules to determine if the game should be allowed to end.

Parameters:

requesterID - String - the id of the player who requested the request.

Returns:

Boolean, TRUE, if successful, FALSE, if not.

rulesPlayerJoin

public boolean rulesPlayerJoin(java.lang.String sender,
                               java.lang.String[] messbody)

This is a shell method to determine if a player will be allowed to join in midgame. Only the Game Master can implement this request.

Parameters:

sender - String - the id of the player who requested the request.

messbody - String[] - the message

Returns:

Boolean - TRUE, if allowed, FALSE, if not

rulescreateTransaction

public boolean rulescreateTransaction(java.lang.String sender,
                                      java.lang.String transtype,
                                      java.lang.String master,
                                      java.lang.String[] players,
                                      boolean pflag)

This method safely allows a player to request the creation of a new transaction of a given type and parameters.

Parameters:

sender - String - the id of the player who requested the request.

transtype - String - the transaction type to be created

master - String - the id of the master of the transaction.

players - String[] - This is an array that holds the Player IDs of the players within the game that are participating in this transaction.

pflag - boolean - This is a flag to describe whether the specific transaction is a private transaction to the non-participating Players.

Returns:

result - Boolean: TRUE, if request sent successfully, FALSE, if not

onBlast

public void onBlast(SPMessageClass messObj)

This method handles incoming new Blast Transactions

Parameters:

messObj - SPMessageClass - incoming Message Object

onnewGameBlock

public void onnewGameBlock(SPMessageClass messObj)

This method handles incoming new Game Blocks

Parameters:

messObj - SPMessageClass - incoming Message Object

getGameinstance

public SPGameClass getGameinstance()

Getter function that returns the property: gameinstance

Returns:

gameinstance - SPGameClass

rulesnewplayerconfig

public boolean rulesnewplayerconfig(java.lang.String pid,
                                    java.lang.String cid,
                                    boolean rflag)

This shell method takes an incoming proposed configuration for a new player and maps it against the local preference for that player, if different.

Parameters:

pid - String - player id of the player to be configured

cid - String - comms id

rflag - boolean - relay flag

Returns:

boolean - whether this is accepted or not