//GUIServices.idl: CORBA interface for the GUI services class. // // 7/12/2000 -- [ET] Version 1.00 release. // 10/4/2000 -- [ET] Added 'getParameterHistory()' method. // 10/12/2000 -- [ET] Added 'getParameterCompSet()' method. // 12/11/2000 -- [ET] Added 'getStationChgdParams()' method. // 4/9/2001 -- [ET] Added 'getSubsetStationsUpdate()' method. // 4/23/2001 -- [ET] Added 'getAgentNames()' and 'getAgentInfo()' // method. // 4/24/2001 -- [ET] Added 'longNamesFlag' param to 'getAgentNames()'. // 8/22/2001 -- [ET] Updated documentation of 'timeVal' parameter of // 'getAgentInfo()' method. // 2/5/2002 -- [ET] Added 'getSameStatusSubsets()' method. // 8/4/2003 -- [KF] Added 'getParameterInformation()' method. // 4/14/2005 -- [KF] Added 'getUseAgentLocationsFlag()' method. // 5/12/2005 -- [KF] Removed 'getUseAgentLocationsFlag()' method. // 5/18/2005 -- [KF] Added 'getExtendedAllStationsUpdate()' method. // 10/4/2007 -- [ET] Added 'getStationSnapshot()' method. // 2/9/2009 -- [ET] Added 'getAllStationsSnapshot()' method. // // //===================================================================== // Copyright (C) 2009 Instrumental Software Technologies, Inc. // // Redistribution and use in source and binary forms, with or without // modification, are permitted provided that the following conditions // are met: // 1. Redistributions of source code, or portions of this source code, // must retain the above copyright notice, this list of conditions // and the following disclaimer. // 2. Redistributions in binary form must reproduce the above copyright // notice, this list of conditions and the following disclaimer in // the documentation and/or other materials provided with the // distribution. // 3. All advertising materials mentioning features or use of this // software must display the following acknowledgment: // "This product includes software developed by Instrumental // Software Technologies, Inc. (http://www.isti.com)" // 4. If the software is provided with, or as part of a commercial // product, or is used in other commercial software products the // customer must be informed that "This product includes software // developed by Instrumental Software Technologies, Inc. // (http://www.isti.com)" // 5. The names "Instrumental Software Technologies, Inc." and "ISTI" // must not be used to endorse or promote products derived from // this software without prior written permission. For written // permission, please contact "info@isti.com". // 6. Products derived from this software may not be called "ISTI" // nor may "ISTI" appear in their names without prior written // permission of Instrumental Software Technologies, Inc. // 7. Redistributions of any form whatsoever must retain the following // acknowledgment: // "This product includes software developed by Instrumental // Software Technologies, Inc. (http://www.isti.com/)." // THIS SOFTWARE IS PROVIDED BY INSTRUMENTAL SOFTWARE // TECHNOLOGIES, INC. "AS IS" AND ANY EXPRESSED OR IMPLIED // WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES // OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE // DISCLAIMED. IN NO EVENT SHALL INSTRUMENTAL SOFTWARE TECHNOLOGIES, // INC. OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, // INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES // (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR // SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) // HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, // STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED // OF THE POSSIBILITY OF SUCH DAMAGE. //===================================================================== // A current version of the software can be found at // http://www.isti.com // Bug reports and comments should be directed to // Instrumental Software Technologies, Inc. at info@isti.com //===================================================================== // module com { module isti { module trinetwatch { module server { module gui_services { interface GUIServices { /* * Returns the table of usage level objects. * @return A formatted ASCII string. */ string getUsageLevelTable(); /* * Returns the table of status level objects. * @return A formatted ASCII string. */ string getStatusLevelTable(); /* * Returns an update on all stations that have changed status * or usage since the given time value. Initially called with * a time value of zero to get a list containing name, usage * and status for all stations. * @param timeVal a server epoch time value (seconds since 1/1/1970). * @return A formatted ASCII string. */ string getAllStationsUpdate(in long timeVal); /* * Returns an extended update on all stations that have changed status * or usage since the given time value. Initially called with * a time value of zero to get a list containing name, usage * and status for all stations. * @param timeVal a server epoch time value (seconds since 1/1/1970). * @return An ASCII string formatted as follows: TTTT;NNNN:SSSSS,UUUUU;... * TTTT;NNNN:SSSSS,UUUUU:LL=LAT,LON... if extended information is available * (all extended information is optional), * where TTTT is the current server time (to be used in subsequent calls), * NNNN is a station name (short station name, 1-5 chars), SSSSS is a status * level tag name, UUUUU is a usage level tag name, * LAT is the station latitude and LON is the station longitude. * For the final string in the information a termination of end of string, * semi-colon (';') or colon (':') should be used. For example the usage * level (UUUUU) text may be terminated by the end of the string, the * semi-colon (';') for the next station or the colon (':') for the next * extended information entry. The same is true for the last value of any * extended extries such as the longitude (LON) entry if it is supplied. * Any number of station/status/usages groups may be passed. * There should be no semi-colon (';') after the last group. */ string getExtendedAllStationsUpdate(in long timeVal); /* * Returns a data set for the given station of detailed information * items that are static in nature. * @param stationName the name of the desired station. * @return A formatted ASCII string. */ string getStationInfo(in string stationName); /* * Returns an update for the given station of detailed information * items that are dynamic in nature and have changed since the given * time value. Initially called with a time value of zero to get a * complete list of dynamic information items. * @param stationName the name of the desired station. * @param timeVal a server epoch time value (seconds since 1/1/1970). * @return A formatted ASCII string. */ string getStationUpdate(in string stationName, in long timeVal); /* * Returns, for the given station, an update of dynamic parameters * that have changed their status level since the given time value. * @param stationName the name of the desired station. * @param timeVal a server epoch time value (seconds since 1/1/1970). * @return A formatted ASCII string. */ string getStationChgdParams(in string stationName, in long timeVal); /* * Returns a list of property strings to be used in a selection * combo-box used to display a subset of stations. * @returns A formatted ASCII string. */ string getPropertyList(); /* * Returns a list of values strings to be used in a selection * combo-box with the given property, to select a subset of stations. * @param propString a string representing the selected property. * @returns A formatted ASCII string, which contains the list of value * strings, and an indicator of which comparison codes may be used * with the given property. */ string getPropValuesList(in string propString); /* * Returns a list of stations that match the given criteria. * @param propString a string representing the selected property. * @param compCode a comparison code, one of the following: * -2 = less than, -1 = less than or equals, 0 = equals, * 1 = greater than or equals, 2 = greater than. * @param valueString a string representing the value entered or * selected by the user. * @return A formatted ASCII string of station names separated by * semicolons, or an empty string if no matching stations could be * found. */ string getSubsetStationsList(in string propString, in long compCode, in string valueString); /* * Returns an update on all stations that match the given criteria * and that have changed status or usage since the given time value. * @param timeVal a server epoch time value (seconds since 1/1/1970). * @param propString a string representing the selected property. * @param compCode a comparison code, one of the following: * -2 = less than, -1 = less than or equals, 0 = equals, * 1 = greater than or equals, 2 = greater than. * @param valueString a string representing the value entered or * selected by the user. * @return A formatted ASCII string. */ string getSubsetStationsUpdate(in long timeVal, in string propString, in long compCode, in string valueString); /* * Sets the usage level for a given station. The method * does not wait for the final confirmation of the usage * level change. (See 'getUsageResult()'.) * @param stationName the name of the desired station. * @param uLevelStr the new usage level for the station. * @return An empty string if the action was successful, * or a text error message string if an error was detected. */ string setStationUsage(in string stationName,in string uLevelStr); /* * Returns the final result of the last call to * 'setStationUsage()' for the given station. * @param stationName the name of the desired station. * @return A text message string decribing the final result * of the attempted level change, or an empty string if * the action is still in progress. */ string getUsageResult(in string stationName); /* * Returns the timeout value associated with the last call to * 'setStationUsage()' for the given station. * @param stationName the name of the desired station. * @return The timeout value, in seconds, for the usage control * change operation in progress; or -1 if the timeout value has * not been set (not yet received from the control agent) or if * a timeout value cannot be generated for the station name. */ long getUsageTimeout(in string stationName); /* * Returns the version string of the NSI server. */ string getNSIVersionString(); /* * Returns the local start time of the NSI server as a string. * @return A string representation of the start time, using the * following format: "Mmm dd, yyyy hh:mm:ss AM/PM". */ string getNSIStartTime(); /* Returns the general help string. */ string getHelpString(); /* Returns the help string for the given station. */ string getStationHelpString(in string stationName); /* * Returns the help string for the given parameter name. */ string getParameterHelpString(in string parmName); /* * Returns the name of the server that this NSI server is receiving * its data from. */ string getServerName(); /* * Returns information for the given parameter from the given station. * @param stationName the name of the desired station. * @param paramName the name of the specified parameter. * @param startSecs starting seconds of the history. * @param endSecs ending seconds of the history. * @param numPoints number of points in the history. * If no match was found then numPoints will be 0. */ void getParameterInformation(in string stationName, in string paramName, out long long startSecs, out long long endSecs, out long numPoints); /* * Returns a set of values and timestamps representing the "history" * of the given parameter from the given station. * @param stationName the name of the desired station. * @param paramName the name of the specified parameter. * @param startSecs number of seconds before the present for the * start time of the range, or 0 for the beginning of the history. * @param endSecs number of seconds before the present for the end * time of the range, or 0 for the end of the history. * @return An ASCII string containing any number of value/time * groups. If no matching value/time groups were found then * an empty string is returned. */ string getParameterHistory(in string stationName, in string paramName, in long startSecs, in long endSecs); /* * Returns the comparison set for the given parameter from the given * station (for its current usage level). The comparison set * consists of groups of value/status-level pairs. * @param stationName the name of the desired station. * @param paramName the name of the specified parameter. * @return An ASCII string containing any number of * value/status-level groups. If no matching groups were * found then an empty string is returned. */ string getParameterCompSet(in string stationName, in string paramName); /* * Returns the names of all the agents reporting to the server. * @param longNamesFlag if true then the "long" versions of the * agent names are returned; otherwise the "short" versions are * returned. * @return An ASCII string formatted as follows: * 'NNNN",...' where NNNN is an agent name, any number of which may * be returned. There should be no comma (',') after the last name. */ string getAgentNames(in boolean longNamesFlag); /* * Returns information about the given agent. * @param agentName the name of the given agent; may be the "short" * or the "long" name of the agent. * @param timeVal if zero then all property items are returned; if * non-zero then only dynamic property items are returned. * @return An ASCII string formatted as follows: * '"NNNN"="VVVV";...' where NNNN is the name of a property and VVVV * represents its value. Any number of property name/value pairs may * be returned. There should be no semi-colon (';') after the last * property. */ string getAgentInfo(in string agentName, in long timeVal); /* * Returns a String indicating all the subset-of-stations sets that * contain stations that are all at the given status level as of the * given server time value. * @param timeVal a server epoch time value (seconds since 1/1/1970). * @param statusLevelStr the name of the status level to use. * @return An ASCII string formatted as follows: * 'TTTT;"PPPP",#,"VVVV";...' where TTTT is the current server time * (to be used in subsequent calls), PPPP is the name of a property * item, '#' is a comparison code and VVVV is a value for the property. * Any number of name,code,value items may be passed. There should be * no semicolon (';') after the last item. If no sets then just the * server time is returned. If error (such as bad 'statusLevelStr') * then an empty string is returned. */ string getSameStatusSubsets(in long timeVal, in string statusLevelStr); /* * Returns an historical snapshot for the given station of detailed * information items (that are of a dynamic nature) at the given time * value. * @param stationName name of the desired station. * @param timeVal server epoch time value (seconds since 1/1/1970). * @return An ASCII string formatted as follows: * 'NNNN;"PPPP":"VVVV",SSSS;...' where NNNN is the short station name, * PPPP is the name of a dynamic parameter, VVVV is the value of the * dynamic parameter and SSSS is the status level tag name for the * dynamic parameter (SSSS may be omitted). Any number of dynamic * parameter name/value/status groups may be passed. There should be * no semi-colon (';') after the last group. */ string getStationSnapshot(in string stationName, in long timeVal); /* * Returns an historical snapshot of all stations at the given time * value. * @param timeVal server epoch time value (seconds since 1/1/1970). * @return An ASCII string formatted as follows: NNNN:SSSSS,UUUUU;... * where NNNN is a station name (short station name, 1-5 chars), SSSSS * is a status level tag name, and UUUUU is a usage level tag name. * Any number of station/status/usages groups may be passed. There * should be no semi-colon (';') after the last group. */ string getAllStationsSnapshot(in long timeVal); /* * Disconnects the calling GUI-client from the SeisNetWatch * server. */ void disconnect(); }; }; }; }; }; };