/*-------------------------------------------------------------------------*/
/**
  @file     rtd_i.h
  @author   N. Devillard
  @date     Jul 2001
  @version  $Revision: 1.4 $
  @brief    Interfaces to RTD.

   This module was freely adapted from the rtdRemote.c module written
   by Allan Brighton. Most differences are related to error handling,
   to make it compliant with eclipse.
*/
/*--------------------------------------------------------------------------*/

/*
	$Id: rtd_i.h,v 1.4 2002/02/15 12:54:18 ndevilla Exp $
	$Author: ndevilla $
	$Date: 2002/02/15 12:54:18 $
	$Revision: 1.4 $
*/

#ifndef _RTD_I_H_
#define _RTD_I_H_

/*---------------------------------------------------------------------------
   							Function prototypes
 ---------------------------------------------------------------------------*/

/*-------------------------------------------------------------------------*/
/**
  @brief    Open a connection to a running RTD.
  @param    pid     PID of the RTD session to connect to.
  @param    host    Name of the host on which RTD is running.
  @param    port    Port number to talk to.
  @return   int 0 for success, 1 for error.

  This function opens a connection to a currently running RTD display.
  The pid, hostname and port number, if not specified (set to 0) are
  read from the file $HOME/.rtd-remote, which is created by RTD
  on startup (see rtdimage/src/RtdRemote.C in the RTD sources).

  The returned value is 0 for success, 1 for error.
 */
/*--------------------------------------------------------------------------*/
int rtdRemoteConnect(int pid, char* host, int port);


/*-------------------------------------------------------------------------*/
/**
  @brief    Disconnect from remote RTD.
  @return   void

  This function disconnects the current process from the running RTD
  session it has been connected to, using rtdRemoteConnect().
 */
/*--------------------------------------------------------------------------*/
void rtdRemoteDisconnect(void);


/*-------------------------------------------------------------------------*/
/**
  @brief    Read answer from the last command sent to RTD.
  @param    sock    Current RTD socket.
  @param    result  Pointer to modify to store result string.
  @return   int RTD status, -1 if error occurred.

  Read the socket with the answer from the last command sent to the
  remote RTD display and return the command's status. The command's
  result is returned in the 'result' argument, which points to local
  or static storage.

  The format of the message read from the socket is:

  @verbatim
  status length\n
  msg[length]\n
  @endverbatim

  where status is 0 (Ok) or 1 and length is the length of the result
  that follows.
 */
/*--------------------------------------------------------------------------*/
int rtdRemoteGetResult(int socket, char** result);


/*-------------------------------------------------------------------------*/
/**
  @brief    Send a command to a remote RTD display.
  @param    cmd     Command to send to RTD display.
  @return   int 0 if Ok, 1 otherwise.

  Write the command to the RTD socket and return 0 if Ok, 1 otherwise.
  "cmd" should not contain a newline, it will be added here.
 */
/*--------------------------------------------------------------------------*/
int rtdRemoteSendOnly(char* cmd);


/*-------------------------------------------------------------------------*/
/**
  @brief    Evaluate an RTD command and return the command status.
  @param    cmd     Command to send to the remote RTD session.
  @return   int status of the command.

  Evaluate the given rtdimage subcommand in the remote rtd application
  and return the status of the command.

  The command syntax is the same as for the "rtdimage" widget (image type),
  except that the instance name is missing.

  Example:
    
  @code
    char* result;
    int status = rtdRemoteCmd("wcscenter", &result);
    if (status == 0) {
        if (sscanf(result, ...) ...) {...}
        ...
    }
  @endcode
 
  On success, "result" points to a char buffer containing the result of
  the command. The buffer is internal and should not be freed and will
  be overwritten in the next call to this routine.
 
  If the command could not be sent, result is set to a NULL pointer and
  an error status (1) is returned.
 */
/*--------------------------------------------------------------------------*/
int rtdRemoteSend(char* cmd, char** result);

#endif