/*-------------------------------------------------------------------- * Name: ism.h * Author: ITEX C-Code Generator * * Copyright 1991-98 Telelogic AB, All rights reserved. * * This Program is owned by Telelogic and is protected by national * copyright laws and international copyright treaties. Telelogic * grants you the right to use this Program on one computer or in one * local computer network at any one time. Under this License you may * only modify the source code for the purpose of adapting it to your * environment. You must reproduce and include any copyright and * trademark notices on all copies of the source code. You may not * use, copy, merge, modify or transfer the Program except as provided * in this License. Telelogic does not warrant that the Program will * meet your requirements or that the operation of the Program will be * uninterrupted and error free. You are solely responsible that the * selection of the Program and the modification of the source code * will achieve your intended results and that the results are * actually obtained. */ #ifndef ISM_H #define ISM_H /*-------------------------------------------------------------------- * About this file: * * This file defines an API for ITEX simulator communication and * control. * * There are some entry points that an adaptor should call on a * regular basis to acheive communication with an ITEX * simulator. Also there is functionality for replacing the ITEX * simulator communication with arbitrary communication mechanisms. */ # ifdef __cplusplus extern "C" { # endif /* __cplusplus */ # include # include /* Used by most modules */ /*-------------------------------------------------------------------- * Enumeration Name: IsmTimeMode * Description: * * Defines the timing mode of the simulator/target tester. There are * two modes: * * IsmRealTime -- Real time is used for the simulation. * IsmDiscreteTime -- Time is only advanced at explicit user command. * * The initial mode is set in the call to IsmMain() defined below. * It is recommended to use realtime for target testers, since * discretetime may invalidate test results. */ typedef enum { IsmRealTime, IsmDiscreteTime } IsmTimeMode; /*-------------------------------------------------------------------- * Function Name: IsmInit * Description: * * Should be called immediately after the call to GciInit(). This shall * be provided argv and argc as provided to the main() function. If the * IsmInit function matches any of the arguments, the argv and argc * variables will be updated (the used arguments will be removed). * * Accepted arguments are: * * -cl Command line mode - use stdin and stdout for communication * -nt Use 'No Tags' in the responses to commands (intended for * human operator). */ extern GciStatus IsmInit( int argc, char ** argv, FILE * in, FILE * out ); /*-------------------------------------------------------------------- * Function Name: IsmExit * Description: * * Use this to clean up and close all channels simui etc. * This function will not close the communications via custom PCOs * as provided by the calls in ets.h */ extern void IsmExit( ); /*-------------------------------------------------------------------- * Function Name: IsmMain * Description: * * Main event loop function for the tester. Call this from the main * function after having initialized any custom PCOs etc. * * In case of abnormal termination of the tester, the function will * return GciNotOk, else GciOk. */ extern GciStatus IsmMain( IsmTimeMode mode ); /*-------------------------------------------------------------------- * Function Name: IsmReadTSPar * Description: * * Should be called by the GciReadTSPar function unless custom * test suite parameter reading has been implemented. */ extern GciValue* IsmReadTSPar( const char * name, const char * pixref ); /*-------------------------------------------------------------------- * Function Name: IsmLog * Description: * * Should be called by the GciLog function. */ extern GciStatus IsmLog( int event, const char * msg ); /*-------------------------------------------------------------------- * Function Name: IsmReport * Description: * * Call this to report a TTCN runtime error. * Also, the message will be appended to the conformance log. */ extern void IsmReport( const char * msg ); /*-------------------------------------------------------------------- * Function Name: IsmError * Description: * * Call this to report a non-recoverable error. This will cause a * error dialog to be displayed in the simulator user interface. * * Also, the message will be appended to the conformance log. */ extern void IsmError( const char * msg ); /*-------------------------------------------------------------------- * Function Name: IsmWarning * Description: * * Call this to report a recoverable error or plain message. This will * cause a error dialog to be displayed in the simulator user interface. * * Also, the message will be appended to the conformance log. */ extern void IsmWarning( const char * msg ); /*-------------------------------------------------------------------- * Function Name: IsmStatus * Description: * * Call this to print a status message in the ITEX toolbar. * * Also, the message will be appended to the conformance log. */ extern void IsmStatus( const char * msg ); /*-------------------------------------------------------------------- * Function Name: IsmSnapshot * Description: * * Call this to implement the Snapshot function. Note that the ets.h * file extends this interface for overriding the functionality for * pco transports. */ extern GciStatus IsmSnapshot( ); /*-------------------------------------------------------------------- * Function Name: IsmStartTimer * Description: * * Call this to implement the GciStartTimer function */ extern GciStatus IsmStartTimer( int timerd, long duration, int unit ); /*-------------------------------------------------------------------- * Function Name: IsmCancelTimer * Description: * * Call this to implement the GciCancelTimer function */ extern GciStatus IsmCancelTimer( int timerd ); /*-------------------------------------------------------------------- * Function Name: IsmCancelTimer * Description: * * Call this to implement the GciReadTimer function */ extern long IsmReadTimer( int timerd ); /*-------------------------------------------------------------------- * Function Name: IsmSend, IsmImplicitSend * Description: * * Call this to implement the GciSend function */ extern GciStatus IsmSend( int pcod, GciValue * object ); extern GciStatus IsmImplicitSend( GciValue * object ); /*-------------------------------------------------------------------- * Function Name: IsmRegisterPCOImplementation * Description: * * This function is used to implement PCO communication with custom * encoding and transport but in the domain of test suites running * under the ism interface. Each of the parameters are described * briefly here. Please see the user documentation for detailed * description. * * Parameter Description * * PCOd Gci descriptor of the pco for which this * implementation should be registered. * * Version A string describing the implementation, * for instance: * "GSM L2 over UDP, v1.0 Copyright (C)1999 Company\n" * "TCAP v 2.1 (C)1999 Company\n" * This string will be printed in the conformance log * when registered to notify the user about the * presense of this custom PCO implementation. * * PollIntervalUS Due to the general design principles of the isim * architecture, all PCOs are polled. Use the * pollinterval to set a maximum polling interval. * The unit is microseconds (us). * * SockFd This can be used to represent a socket or file * descriptor which MAY be used in a select(3C) call * by the internals of the ism interface to improve * the response times. Even if this is used, it is * not to be assumed that a call to Poll() has been * preceeded by a call to the select function. A value * of -1 shall be used if the parameter is not used. * Note: In order to change this SockFd as registered * (may be needed if configured as server socket), do * first unregister the PCO implementation and then * call this method again with the updated value. * Note: For Win32 implementations, only use with * 'winsock' socket interface descriptors. * * Info This pointer is not interpreted by the internal code * but may be used to associate some information related * to the specific implementation of the PCO. The info * pointer will be passed to all subsequent calls to * the below function pointers. * * Send This is a pointer to a function that performs a * send on the pco. The function is expected to encode * the message and then send it over the pco. * A return value of GciNotOk indicates an error, but * it is not guaranteed to terminate the tester. * * Poll This is a pointer to a function that should poll * the PCO. If a complete message has been received, * it shall be decoded and returned. A return value * of NULL shall be used to indicate that no message * is ready to read. Note that a period of up to the * default polling interval may pass until the next * call. * * Reset This is a pointer to a function that may be called * to reset the PCO in case a test case is terminated. * Any partly decoded messages may be discarded. A * no-op should be ok as well (i.e, a NULL pointer is * valid). This is also called from the IsmExit() * function. */ extern GciStatus IsmRegisterPCOImplementation( int PCOd, const char* Version, long PollIntervalUs, int SockFd, void* Info, GciStatus (*Send)( void* Info, GciValue* obj ), GciValue * (*Poll)( void* Info ), GciStatus (*Reset)( void* Info ) ); /*-------------------------------------------------------------------- * Function Name: IsmUnregisterPCOImplementation * Description: * * Remove any references to a previously registered PCO * implementation. This ensures that there are no more references to * this PCO implementation. Note that the result of registering a * PCO implementation twice for a given PCO is undefined. Always * 'unregister' a PCO implementation before registering a new one. * It is also recommended to do this before destroying the PCO. */ extern GciStatus IsmUnregisterPCOImplementation( int PCOd ); /*------------------------------------------------------------------*/ # ifdef __cplusplus }; # endif /* __cplusplus */ #endif /* ISM_H */