//
// Casino.idl - This is the full set of interfaces for the Virtual Casino
//              Client/Server Application.
// Authors    - Team5
// Date       - Jan 31, 2003
// 
// NB: compile me with idlj -fall -pkgPrefix Casino edu.cmu.mse17654 Casino.idl
//


/** The Casino Module holds all the interfaces for the Virtual Casino Project
 */
module Casino {
  
  /**
   * An exception meant to be raised when a player tries to buy chips
   * without enough fund on his/her credit card
   * @version 0.1
   * @author Team5
   */
  exception InsufficientMoney {
	
    /** The amount of money needed for the transaction*/
    short requested;
    /** The players credit card balance */
    short balance;
  };
	
  /**
   * An exception meant to be raised when a player tries to buy bet
   * more chips than he/she has.
   * @version 0.1
   * @author Team5
   */
  exception InsufficientChips {
	
    /** The amount of chips needed for the transaction*/
    short requested;
    /** The players chip balance */
    short balance;
  };

  /** A non-existant or impossible SessionID has been passed to a method*/
  exception InvalidSessionID {

    /**The invalid id used */
    short idUsed;
  };

  /** A credit card information is poorly formed or non-existant*/
  exception InvalidCredit {
    /** The Credit Card information passed to the method*/
    short CreditCardInfoUsed;
  };

  /** The system is not able to provide a table for the player
   *  to play at.
   */
  exception no_more_tables {};

  /**
   * Callback interface for server(s) to "pull" from clients.
   * <ul><li>Category: Baseline (fulfills requirement #8)</li>
   * <li>Behavior: This interface provides the callback methods of a player.
   *  The dealer leads the Blackjack game, and the players react to the
   *  dealer's commands and requests. During the game client 
   *  and server roles are swapped.</li>
   * <li>Inherits From: </li>
   * <li>Clients: Dealer</li></ul>
   * @version 0.1
   * @author team5
   */
  interface Player {
		
    /**
     * A dealer request for a player to bet on his/her cards.
     * <ul><li>Category: Baseline</li>
     * <li>Behavior: The player is prompted for his bet for the next game.</li>
     * <li>Clients: Dealer</li></ul>
     * @parm amount The client's bet in chips.
     * @returns void
     * @raises InsufficientChips If the player has no chips to bet
     */
    void placeBet(out short amount)
      raises(InsufficientChips);
 
    /**
     * A dealer sends a card to a player
     * <ul><li>Category: Baseline</li>
     * <li>Behavior: This method passes a card to the player.</li>
     * <li>Clients: Dealer</li></ul>
     * @parms cardID The ID of the new card.
     * @returns void
     */
    void acceptCard(in octet cardID);

    /**
     * The dealer is giving a player another player's card to view.
     * <ul><li>Category: Baseline</li>
     * <li>Behavior: A player client uses this method to register for a session
     *           at the casino server.</li>
     * <li>Clients: Dealer</li></ul>
     * @parm playerID The number (1..4) of the other player at the 
     *                table who gets this card.
     * @parm cardID The ID of the new card.
     * @returns void
     */
    void acceptOthersCard(in short playerID,
			  in octet cardID);
    /**
     * The dealer is telling the player that the game is starting
     * <ul><li>Category: Baseline</li>
     * <li>Behavior: Start a new game at the current table.</li>
     * <li>Clients: Dealer</li></ul>
     * @parm numberOfPlayers The number of players at the table.
     * @returns void
     */
    void startGame(in octet numberOfPlayers);

    /**
     * The dealer is asking the player to stay or hit.
     * <ul><li>Category: Baseline</li>
     * <li>Behavior: Ask the player what he/she wants to do next.
     * Either get a another card (HIT) or not (STAY).</li>
     * <li>Clients: Dealer</li></ul>
     * @parm choice
     * @returns void
     */
    void playerOption(out octet choice);

    /**
     * The dealer is telling the player that the game if over.
     * <ul><li>Category: Baseline</li>
     * <li>Behavior: Let the player know that the game is over, if he has won,
     *           and his new chip balance.</li>
     * <li>Clients: Dealer</li></ul>
     * @parm won True iff the player has won.
     * @parm newBalance The new chip balance of the player.
     * @returns void
     */
    void gameOver(in boolean won, 
		  in short newBalance);
    
    /**
     * The dealer is kicking the player off the game for misbehavior
     * <ul><li>Category: Realtime </li>
     * <li>Behavior: If a player does not place a bet or choose an option 
     *           within the allotted amout of time, the Dealer kicks 
     *           him out.</li>
     * <li>Clients: Dealer</li></ul>
     * @returns void
     */
    void kickOut();
  };

    
  /**
   * An exception raised to indicate that a non-existant player has been
   * passed to a method.
   */
  exception InvalidPlayer {
    /** The player passed to the method.*/
    Player playerUsed;
  };
	
  /**
   * The interface used to simulate monetary transactions
   *<ul><li>Category: Baseline (fulfills baseline requirements #1 & #5)</li>
   *<li>Behavior: This interface supports methods to simulate the 
   *          buying and selling of gambling chips.</li>
   *<li>Clients:  Player</li></ul>
   * @author team5
   * @version 0.1
   */
  interface Bank {
		
    /**
     * The player is purchasing chips from the bank.
     * <ul><li>Category: Baseline.</li>
     * <li>Behavior: The player give his/her (simulated) credit card information
     *           and quantity of chips requested and is given that number of
     *           chips.  If there is not enough money in the credit account
     *           an exception is thrown.</li>
     * <li>Clients:  Player</li></ul>
     * @parm quantity The number of chips requested.
     * @parm CreditCardInfo The simulated credit card.
     * @returns void
     * @raises InsufficientMoney
     * @raises InvalidCredit
     */
    void buyChips(in Player player,
		  in short quantity,
		  in short CreditCardInfo)
      raises(InsufficientMoney,
	     InvalidCredit);
		
    /**
     * The player is selling chips back to the bank.
     * <ul><li>Category: Baseline.</li>
     * <li>Behavior: The player sells all or some of his chips back to the
     *           Bank.</li>
     * <li>Clients:  Player</li></ul>
     * @parm quantity The number of chips to be sold.
     * @returns void
     * @raises InsufficientChips
     */
    void sellChips(in Player player,
		   in short quantity)
      raises(InvalidSessionID,
	     InsufficientChips);

    /**
     * The player requests the number of chips he/she owns
     * <ul><li>Category: Baseline.</li>
     * <li>Behavior: The player requests the balance of chips from the bank.</li>
     * <li>Clients:  Player</li></ul>
     * @parm sessionID The current gaming session.
     * @parm quantity The number of chips to be sold.
     * @returns void
     * @raises InsufficientChips
     */
    short getChipBalance(in Player player)
      raises(InvalidPlayer,
	     InsufficientChips,
	     InvalidSessionID);
  };
    

  /**
   * The set of gaming tables 
   * <ul><li>Category:  Baseline (fulfills baseline requirment #4)</li>
   * <li>Behavior:  This interface supports methods to allow a player
   *           to join a game at a virtual table.</li>
   * <li>Clients: Player</li></ul>
   * @author team5
   * @version 0.1
   */
  interface Tables {
     
    /**
     * Player asks to join any table.
     * <ul><li>Category: Baseline </li>
     * <li>Behavior: Enables a player to join a table.</li>
     * <li>Clients: Players</li></ul>
     * @parm player The player object reference.
     * @parm sessionID The table session that the player joined.
     * @returns void
     * @raises InvalidPlayer The player object is invalid.
     */
    void joinTable(in Player player, 
		   out short sessionID)
      raises(InvalidPlayer);

    /**
     * Player elects to leave a game.
     * <ul><li>Category: Baseline </li>
     * <li>Behavior: Enables a player to leave a table.</li>
     * <li>Clients: Players</li></ul>
     * @parm sessionID The table session for the player.
     * @returns void
     * @raises InvalidSessionID The passed sessionID is invalid.
     */
    void leaveTable(in short sessionID)
      raises(InvalidSessionID);
  };

  /**
   * The "floor" of the casino, containing many tables
   * <ul><li>Category: Baseline (fulfills requirement #1)</li>
   * <li>Behavior: This interface is the main entrance into the casino.</li>
   * <li>Inherits From:</li>
   * <li>Exceptions: CORBA System exceptions</li>
   * <li>Clients: Player</li></ul>
   * @author team5
   * @version 0.1
   */
  interface Floor {

    /**
     * The new or returning player registers with the system to start
     * <ul><li>Category: Baseline</li>
     * <li>Behavior: A player client uses this method to register for a session
     *           at the casino server.</li>
     * <li>Clients: Player</li></ul>
     * @parm player The client's Player interface.
     * @parm bank The casino's Bank to buy chips
     * @parm tables The Blackjack table manager.
     * @returns void
     * @raises InvalidPlayer
     */
    void register(in Player player,
		  out Bank bank,
		  out Tables tables)
      raises(InvalidPlayer);
  };
};