/* ***************************************************************************+
 * ITX package (cnrg.itx) for telephony application programming.              *
 * Copyright (c) 1999  Cornell University, Ithaca NY                          *
 *                                                                            *
 * This program is free software; you can redistribute it and/or modify       *
 * it under the terms of the GNU General Public License as published by        *
 * the Free Software Foundation, either version 2 of the License, or (at      * 
 * your option) any later version.                                            *
 *                                                                            *
 * The ITX package is distributed in the hope that it will be useful, but     *
 * WITHOUT ANY WARRANTY, without even the implied warranty of MERCHANTABILITY *
 * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License   *
 * for more details.                                                          * 
 *                                                                            *
 * A copy of the license is distributed with this package.  Look in the docs  *
 * directory, filename GPL.                                                   *
 *                                                                            * 
 * Contact information:                                                       *
 * Donna Bergmark                                                             *
 * 484 Rhodes Hall                                                            *
 * Cornell University                                                         *
 * Ithaca, NY 14853-3801                                                      *
 * bergmark@cs.cornell.edu                                                    *
 ******************************************************************************/

package cnrg.itx.gtwy;
import cnrg.itx.datax.Channel;
import cnrg.itx.datax.devices.*;

/**
 * This is the building block interface between a class and a Gateway channel hardware control.
 * NOTE: This accesses the native C code
 * 
 * @author James Wann
 * @version 1.0a
 */
public class ChannelControl
{
	static 
	{
		System.loadLibrary("Dialogic");
    }
	
	/**
	 * Initializes parameters in the .cpp file.  Called when Gateway starts.
	 * 
	 * @param numLines the number of lines in the gateway.
	 * @param bufferSize the packet transfer rate between the gateway and phone.
	 * @param dataSize the packet transfer rate of data exchange.
	 * @param pXferFactor factor bufferSize is multiplied by to define size of packets played to phone.
	 * @see Gateway#Gateway(boolean)
	 */
	protected native void initialize(int numLines, int bufferSize, int dataSize, int pXferFactor);

	/**
	 * Closes all Gateway channels and cleans up memory.  Called at termination of the Gateway.
	 * 
	 * @param chDevArray array of all channel device handlers.
	 */
	protected native void shutDown(int[] chDevArray);
	
	/**
	 * Used for channel initialization.  Called during the initialization of the Gateway.
	 * 
	 * @param channelNum the channel's designated number.
	 * @param xferFactor to be multiplied with the packet transfer rate.  Meant to increase transfer
	 * rate if desired.
	 * @return the channel's device handler.
	 * @see Gateway#Gateway(boolean)
	 */
	protected native int channelSetUp(int channelNum, int xferFactor);
	
	/**
	 * Reroutes the second channel's playout to the primary channel's playout.  Necessary for a full
	 * duplex connection.
	 * 
	 * @param chDev the primary channel's device handler.
	 * @param secDev the second channel's device handler.  This channel is responsible for playout.
	 * @see Gateway#setUpConnection(Line, Connection)
	 */
	protected native void reroute(int chDev, int secDev);
	
	/**
	 * "Releases" the second channel from playing out on the primary channel.
	 * 
	 * @param chDev the primary channel's device handler.
	 */
	protected native void unroute(int chDev);
	
	/**
	 * Sets the channel on hook.  Channel is available to receive incoming calls from a phone.
	 * 
	 * @param chDev the channel's device handler.
	 */
	protected native void channelOnHook(int chDev);
	
	/**
	 * Sets the channel off hook to allow for passing voice data through.
	 * 
	 * @param chDev the channel's device handler.
	 * @see Gateway#setUpConnection(Line, Connection)
	 */
	protected native void channelOffHook(int chDev);
	
	/**
	 * Sets up the channel to wait for a phone to dial in.
	 * 
	 * @param chDev the channel's device handler.
	 * @see ListenChannel#run
	 */
	protected native void waitForCall(int chDev);
	
	/**
	 * This is where the channel gets the phone's requested extension number.  Number corresponds with
	 * whomever phone user wishes to contact.
	 * 
	 * @param chDev the channel's device handler.
	 * @param isSecondTime true if this is not the first call to getExtension during session.
	 * @return the extension number.
	 * @see ListenChannel#run
	 */
	protected native String getExtension(int chDev, boolean isSecondTime);
	
	/**
	 * Plays out a message to a phone when a call has been rejected.
	 * 
	 * @param chDev the channel's device handler.
	 * @see ListenChannel#run
	 */
	protected native void rejectCallMessage(int chDev);
	
	/**
	 * Dials a phone.  Returns as soon as the phone starts ringing or something goes wrong.
	 * 
	 * @param digits the phone number being dialed.
	 * @param chDev the channel's device handler.
	 * @return true if phone rings; false if something went wrong or the phone is busy.
	 * @see Gateway#dialPhone(String, Line)
	 */
	protected native boolean dialPhone(String digits, int chDev);
	
	/**
	 * Plays DTMF tones to the telephone connected to the line.
	 * 
	 * @param digits the DTMF digits being played.
	 * @param chDev the channel's device handler.
	 * @see Gateway#playDTMF(String, Line, Connection)
	 */
	protected native void playDTMF(String digits, int chDev);
	
	/**
	 * Sends voice data from phone to computer.
	 * 
	 * @param dataChannel the object whose methods are used to send data to a PC.
	 * @param chDev the channel's device handler.
	 * @param lineNumber the channel's corresponding line number.
	 * @return any DTMF digits that were pressed during recording or an indication of a hangup.
	 * @see RecordChannel#run
	 */
	protected native String recordPacket(RecordSource dataChannel, int chDev, int lineNumber);
	
	/**
	 * Plays voice data from a buffer to a phone.
	 * 
	 * @param chDev the channel's device handler.
	 * @param lineNumber the channel's corresponding line number.
	 * @see PlayChannel#run
	 */
	protected native void playPacket(int chDev, int lineNumber);
	
	/**
	 * Writes voice data from computer to buffers in native code.  <code>playPacket</code> plays out the
	 * data in the buffers.
	 * 
	 * @param lineNumber the line's designated number.
	 * @param data the data being sent.
	 * @see #playPacket(int, int)
	 * @see PlayDestination#write(byte[])
	 */
	protected native void writeToPlay(int lineNumber, byte[] data);
	
	/**
	 * Resets handlers for sending data from phone to computer.  Handlers are set to designate that the
	 * connection is still alive.
	 * 
	 * @param lineNumber the channel's corresponding line number.
	 * @param isStartCall true if this is the beginning of a connection session; false otherwise.
	 */
	protected native void resetRecordSequence(int lineNumber, boolean isStartCall);
	
	/**
	 * Resets handlers for a playout on a phone.  Handlers are set to designate that playout is still
	 * active.
	 * 
	 * @param lineNumber the channel's corresponding line number.
	 * @param isStartCall true if this is the beginning of a connection session; false otherwise.
	 */
	protected native void resetPlaySequence(int lineNumber, boolean isStartCall);
	
	/**
	 * Terminates the data flow from phone to computer.
	 * 
	 * @param lineNumber the channel's corresponding line number.
	 */
	protected native void endRecordConnection(int lineNumber);
	
	/**
	 * Stops audio playout from computer to phone
	 * 
	 * @param lineNumber the channel's corresponding line number.
	 */
	protected native void endPlayConnection(int lineNumber);
}