Status API

Revision as of 10:40, 9 June 2010

******* Getting used with Status API **********

Status API consists of status request queries based on a "path". Each status has a path, like:

/adapter
/adapter/ip_interface
/isup/interface
/clock/ref
etc.

We already provide two ways of accessing the Toolpack Status:

- Web Portal
- Command-line tool "tbstatus", that you will find installed within toolpack installation under /lib/tb/toolpack/pkg/2.X.X/bin/release/[your_platform]/tbstatus

******* Viewing status tree using Web Portal **********

I suggest that you start by using the "browse" option in the WEB portal:
Go to the Web Portal -> Status -> Browse
This tool will list available paths that can be queried.
When you click one of these paths, the web page will show a table that list all fields returned from that path.

******* Viewing status tree using the command-line tool **********

The command-line tool will also allow getting a list of available paths:

[i]./tbstatus [/i]

You can also query stats using one of these path, result is formatted as text output:

[i]./tbstatus /adapter [/i]

Example above show stat of all adapters. You can query more specific stats too:

[i]./tbstatus /adapter:TB005432 [/i]

Or you can query "recursive" information that also includes paths "under" a base path:

[i]./tbstatus /adapter:TB005432/* [/i]

Or you can query very deep and specific information:

[i]./tbstatus /isup:ISUP/interface:ISUP_INTERFACE/cic_group:C002020_2_0_12[/i]

******* Paths for ISUP Circuit states **********

You can query states for one circuit group using a path like this one (replace C002020_2_0_12 by your circuit group name, as seen in it's Web portal configuration):

[i]./tbstatus /isup/interface/cic_group:C002020_2_0_12[/i]

If you're using version 2.4 or up, you also have access to individual circuits states... but you HAVE to use "-x" option (extended stats mode) to get these. To get states for all CICs of a group:

[i]./tbstatus [u]-x[/u] /isup/interface/cic_group:C002020_2_0_12/*[/i]

For example, to get states for CIC #1705, you can use:

[i]./tbstatus -x /isup/interface/cic_group/cic:1705[/i]

******* Querying/modifying individual field value using the command-line tool **********

To query individual field value, you add "::" after the path, then specify the specific field name. For example:

[i]./tbstatus /isup/interface/cic_group/cic:1705::desired_cic_state[/i]

Or to modify the circuit state (here to force blocking state):

[i]./tbstatus /isup/interface/cic_group/cic:1705::desired_cic_state=Blocked[/i]

• Note: Remember that this change is PERSISTENT, which means circuit will remain blocked forever (no matter trunk state) until you change it again (to "Default", or "Unblocked" for example).

******* How to write code that use that API **********

Now that you understand a bit how Status API works, here is sort explanation on how to write code to manipulate these states.

In short you need to create and start the status client service in your application:

 pClient = tbnew CTBCAFServiceStatusClient();
 pClient->Start();

Then each available stat is reported under a "path". Your code can call following function to get available paths:

 pClient->GetRegisteredPaths();

Once you know the path you want to query, you can retrieve the stats, either synchronously or asynchronously: Synchronously:

 pStatList = pClient->GetStat(
   "your_path",
   "x"
 );

Asynchronously:

 pClient->ReqStat(
   pMyStatPipe,
   "your_path",
   "x"
 );

Available options:

- Option "x" passed to in_pszOptions means "extended" stats query (provides more detailed stats in some cases, like individual circuits)
- Option "d" will make documentation be returned for each field with the query response (by default, only field names and values are returned)

For more information on "pMyStatPipe", please read documentation from the header files in the code.

Once you get your "pStatList", you can get each item it returned (there can be many if your request matches many):

 pStat = pStatList->GetItem( un32StatIdx );

And for each item, you can get list of fields:

 pFieldList = pStat->GetFields();

... and list each field (one field is one individual stat value):

 pField = pFieldList->GetItem( un32FieldIdx );

Now, as you traverse the stat tree, you will encounter some values that can be changed using:

 pField->Set( "new value" );

Once you have changed one or more fields of the stat, you can commit it:

 pStat->CommitStates();

For more detailed information, please refer to the source code of the "tbstatus" application, and to documentation in appropriate header files.

******* Note **********

In order to get/set individual circuits states, you need:
- Release 2.4 or more recent, since release 2.3 allowed only to change state per circuit group... (per trunk in other words)
- Need to use "-x" in the options field of GetStat, as per-circuit stats are shown only in "extended" mode