User interface scripts allow you to add custom functionality to the Unsniff Network Analyzer application. You can attach custom scripts to menu items. Your scripts will be triggered when the user selects the corresponding menu item.
In addition to all the objects you have seen in Section 3. Scripting Object Model – you get access to the following objects.
You can attach custom scripts to the following menus in Unsniff.
| Capture Menu | Use this menu if your scripts work on the entire capture file independent of the user selection. |
|---|---|
| Packet sheet context menu | You can add a menu item to the packet sheet context menu. This context menu is shown when the user right clicks on the packets sheet. Use this is your script needs to work on selected packets. |
| PDU sheet context menu | Add a menu item to the PDU sheet context menu. Use this method if your script needs to work with selected PDUs. |
| Streams sheet context menu | Add a menu item to the Streams sheet context menu. This works on entire streams. Use this method if your script needs to work with selected streams. |
| User Objects sheet Context menu | Add a menu item to the User Objects sheet context menu. Use this method if you want to work with selected user object |
Script Integration Points
ou can integrate your scripts into Unsniff via Tools → User Scripts. Step-by-step example
Assume that you have written a custom RTP Analysis script. This script analyzes an entire RTP session of a selected RTP packet that is part of the session. In this case you may wish to activate this script from the packets sheet context menu. Here is a step-by-step.
| Name | A short name for the script functionality |
|---|---|
| Context | Select where you want to attach your scripts. Five menu options are provided, you need to select one from the drop down list |
| Menu Tag | A menu tag identifies how your script will be merged with the existing menu. You can use a “\” (backslash) character to create nested menus. In the above example RTP\RTP Analysis is a nested menu. You are encouraged to use nested menus to group related scripts together. |
| Description | Optional description |
| Script file | Click the browse button to select your script file. A script file must follow these rules. - VBScript files must have an extension *.vbs - Ruby files must have an extension *.rb - Jscript files must have an extension *.js |
-Click OK – then restart Unsniff for your changes to take effect. The figure below shows a custom RTP Analysis script attached to the Packets sheet context menu.
Your script will automatically have access to an object called “CurrentDocument”. This object provides you with access to the currently active capture file as well as the current selection context. Here is a list of properties and method of this object.
| Name | Type | Access | Description |
|---|---|---|---|
| DatabaseName | String | Read | Name of the currently open capture file |
| Console | Object | Read | Creates a new scripting console object. This can be used to output results of your script. See the next section for a list of properties and methods for the Console object. |
| PacketCount | Long | Read | Number of packets in the currently open capture file |
| PacketIndex | Collection | Read | A collection of Packet objects. This represents all the packets in the capture file. |
| SelectedPacket | Object | Read | The selected packet if a single packet (or) The first selected packet if multiple packets are selected |
| SelectedPackets | Collection | Read | All selected packets (a collection of Packet objects) |
| PDUCount | Long | Read | Number of PDUs in the currently open capture file |
| PDUIndex | Collection | Read | A collection of PDU objects. This represents all the PDUs in the currently active capture file |
| SelectedPDU | Object | Read | The selected PDU if single selection (or) The first selected PDU if multiple selection |
| SelectedPDUs | Collection | Read | All selected PDUs (a collection of PDU objects) |
| StreamCount | Long | Read | Number of streams in the currently open capture file |
| StreamIndex | Collection | Read | A collection of Stream objects. This represents all streams in the currently active capture file. |
| SelectedStream | Object | Read | The selected stream |
| SelectedStreams | Collection | Read | All selected streams (a collection of Stream objects) |
| UserObjectsCount | Long | Read | Number of user objects in the currently open capture file |
| UserObjectsIndex | Collection | Read | A collection of UserObject objects. This represents all the user objects in the currently active capture file. |
| SelectedUserObject | Read | The selected user object (or) The first selected user object if multiple selection | |
| SelectedUserObjects | Collection | Read | All selected user objects (a collection of UserObject objects) |
This object does not define any methods
Unsniff provides a powerful console via the CurrentDocument.Console object. The script console provides rich formatting features that can be used to create great reports. The properties and methods of the Script console are shown below.
| Name | Type | Access | Description |
|---|---|---|---|
| TextColor | String | Read/Write | The current text color. The format of the text color is #RRGGBB. The RGB components are specified in hex. For example: Con.TextColor = “#FF0000” Will set the current text color to full red. |
| Bold | Boolean | Read/Write | The current bold text style. This is a boolean value. In VBScript: Con.Bold = True In Ruby: Con.Bold = true |
| Hilite | Boolean | Read/Write | The current hilite style. Hilited text appears in a yellow hilite background. |
| Italics | Boolean | Read/Write | The current italic style. |
| Name | Parameters | Description |
|---|---|---|
| Write | String | Write the string to the console using the current styles |
| WriteLine | String | Write the string to the console using the current styles. This method automatically appends the required CR+LF characters. New text will start on a separate line. |
| SetDefaultFormat | None | Reset all styles. Set TextColor to black. |
| SetTitle | String | Set the title of the script console window |
| Clear | None | Clear the contents of the script console window |
A simple example will illustrate the use of the CurrentDocument and the Script Console. Task : Print a description of each selected packet (Packet.Description)
> VBScript ' --------------------------------- ' Get access to the script console ' --------------------------------- Dim Con Set Con = CurrentDocument.Console Con.TextColor = “#55EE33” Con.WriteLine “Packet Printer Demo” Con.WriteLine “-------------------“ Set SelPacketList = CurrentDocument.SelectedPackets For Each Packet In SelPacketList Con.WriteLine Packet.Description Next