Class Documentation
Inspector |
1.1 |
ID_INSPECTOR |
Unspecified |
Tool |
May 2001 |
Rocklyte Systems |
Rocklyte Systems (c) 2000-2001. All rights reserved. |
This class allows the user to inspect the system structure. |
Description
Inspector is a tool-based class that can be used as a command or implemented
as an application. It is designed for user interactivity and can execute a
wide variety of commands that can be used to 'inspect' the underlying system
structure. As well as providing facilities for system analysis, support for
the manipulation of public objects is also provided.
To create a valid Inspector object, all you need to do is set the Output
field, decide whether the object should be Static or not, and set the Command
field as and when a new command needs to be executed. If you are creating
an application based on the Inspector class, you should set-up an input box
connected to the Command field so that the user can type in commands for the
Inspector object to execute. An example of an existing Inspector application
can be found in the scripts:development/monitors/ directory.
To find out what commands Inspector supports, open the existing Inspector
application and type 'help' into the input box. This will provide you with
a list of all supported commands and the arguments that can be passed to
them.
Actions
The Inspector class supports the following actions:
Activate | Executes the instructions specified in the Command string. |
ClosingTag | If the object is non-static, this action will execute the requested command and then the object will self-destruct. |
Methods
The Inspector class implements the following methods:
About | Prints general information about the Inspector class and what it does. |
Help | Prints instructions on how to use Inspector. |
HexDump | Dumps public memory block information in hex format. |
ListMemory | Lists all public memory blocks that exist in the system. |
ListObjects | Lists all public objects that exist in the system. |
ListResources | Can list the resources belonging to any specific public object. |
MemoryInfo | Can print information on any specific public memory block. |
TextDump | Dumps shared memory blocks in text format. |
Tree | Prints a tree-like view of an object's contents. |
ViewObject | Interrogates public objects for information and prints their details. |
Structure
The Inspector object consists of the following public fields:
Command | Set this field prior to activation for a command to be executed. |
Output | Set this field to the object that is to receive Inspector's output. |
Quit | If Inspector is used as an application, point this field to the application's window. |
Activate |
Executes the instructions specified in the Command string. |
Activating an Inspector object causes it to analyse the
Command field and print the results to the object
specified in the Output field.
|
|
About() |
Prints general information about the Inspector class and what it does. |
Executing the About method will print general information about the
Inspector class, such as who wrote it and what it is designed for.
ERR_Okay | The method executed successfully. |
ERR_FieldNotSet | The Output field has not been set. |
|
|
Help() |
Prints instructions on how to use Inspector. |
The Help method prints a list of commands that can be used to interact
with Inspector, as well as details on their supported arguments and a short
summary of what the commands do.
ERR_Okay | The method executed successfully. |
ERR_FieldNotSet | The Output field has not been set. |
|
|
HexDump() |
Dumps public memory block information in hex format. |
MEMORYID MemoryID | The memory ID to be hex-dumped must be specified here. |
LONG Length | The maximum number of bytes to be printed. |
|
This method can be used to get a hex-based read-out of a public memory
area. This is extremely useful for getting a closer peek at what a memory
block actually contains. The printed information is laid out in the standard
format for hex dumping, that is in lines of 16 numbers followed by the
text-based equivalent of each number. The maximum number of bytes to be
printed by the method must be specified in the Length argument, which
prevents too much information from being printed in the case of large
memory blocks.
ERR_Okay | The method executed successfully. |
ERR_Args | Invalid arguments were detected. |
ERR_FieldNotSet | The Output field has not been set. |
ERR_AllocMemory | An attempt to allocate sufficient buffer space failed. |
ERR_AccessMemory | The given memory ID could not be accessed. |
|
|
ListMemory() |
Lists all public memory blocks that exist in the system. |
The ListMemory method prints a list of all public memory blocks that
have been allocated within the system. The information covers the memory
ID, byte size, access-count and the ID of the owner for each memory
block.
After obtaining a memory list, further analysis can be done by using
commands such as HexDump, TextDump and MemoryInfo.
ERR_Okay | The method executed successfully. |
ERR_FieldNotSet | The Output field has not been set. |
ERR_GVBaseDenied | An attempt to gain access to the GVBase failed. |
ERR_AllocMemory | An attempt to allocate sufficient buffer space failed. |
|
|
ListObjects() |
Lists all public objects that exist in the system. |
The ListObjects method prints a list of all public objects that exist
within the system. Information is given for the class, object ID, and
memory ID of the object structure.
After obtaining a list of objects, further information on individual
objects can be gained by using the View command.
ERR_Okay | The method executed successfully. |
ERR_FieldNotSet | The Output field has not been set. |
ERR_AccessMemory | The method could not gain access to the PublicObjects table. |
ERR_GVBaseDenied | The method could not gain access to the GVBase. |
ERR_AllocMemory | The system is low on memory. |
|
|
ListResources() |
Can list the resources belonging to any specific public object. |
OBJECTID ObjectID | This parameter must refer to the object that is to be analysed. |
|
The ListResources method can be used to list the memory and children that
belong to a public object. All you need to supply is the public ID of the
object you want to analyse.
ERR_Okay | The method executed successfully. |
ERR_Args | Invalid argument settings were detected. |
ERR_ExclusiveDenied | Inspector could not gain access to the Output object. |
|
|
MemoryInfo() |
Can print information on any specific public memory block. |
MEMORYID MemoryID | This argument must refer to the public memory block that you want to analyse. |
|
If you require detailed information on a public memory block, this
method can be used to obtain the byte size and owner of the block.
ERR_Okay | The method executed successfully. |
ERR_Args | Invalid arguments were detected. |
ERR_Memory | Inspector failed to obtain memory information for the given ID. |
ERR_AllocMemory | A call to AllocMemory() failed. |
|
|
TextDump() |
Dumps shared memory blocks in text format. |
MEMORYID MemoryID | The memory ID to be text-dumped must be specified here. |
LONG Length | The maximum number of characters to be printed. |
|
This method can be used to get a text-based read-out of a public memory
area. This is extremely useful for getting a closer peek at what a memory
block actually contains. The printed information is laid out in a stream of
48 bytes per line. The maximum number of bytes to be printed by the method
must be specified in the Length argument, which prevents too much information
from being printed in the case of large memory blocks.
ERR_Okay | The method executed successfully. |
ERR_Args | Invalid arguments were detected. |
ERR_FieldNotSet | The Object field has not been set. |
ERR_AccessMemory | Inspector could not gain access to the given memory ID. |
|
|
Tree() |
Prints a tree-like view of an object's contents. |
OBJECTID ObjectID | The ID of the object you wish to examine, or NULL if you are specifying a Name. |
STRING Name | The name of the object you wish to examine, or NULL if you are specifying an ID. |
|
This method can examine any public object and print a complete, hierarchical
list of all other objects that belong to it. For instance, if you were to
view a tree of a Window on the display, you would get a read-out of all
objects within it - i.e. gadgets, graphical objects, interactive objects and
so forth. With such an overview you can then examine certain objects in more
detail by using the View command.
ERR_Okay | The method executed successfully. |
ERR_Args | Invalid arguments detected. |
ERR_FieldNotSet | The Output field has not been set. |
|
|
ViewObject() |
Interrogates public objects for information and prints their details. |
OBJECTID ObjectID | The object to be viewed must be referred to in this field. |
|
The ViewObject method is a field analyser for public objects. Simply
provide it with a valid object ID and the method will list all of the fields
that belong to the object, as well as the values associated with each field.
This functionality is especially useful for debugging purposes and
manipulating the system when used in conjunction with the 'setfield'
command.
You may notice that some field-types are not printed, e.g. pointer-based
fields. This is because the memory addresses used by public objects are
dynamic, which means that memory pointers can 'shift'. Other field types
that have no read-access are also marked as being unreadable.
ERR_Okay | The method executed successfully. |
ERR_Args | Invalid arguments were detected. |
ERR_FieldNotSet | The Output field has not been set. |
ERR_ExclusiveDenied | Inspector could not gain exclusive access to the given object. |
|
|
Field: | Command |
Short: | Set this field prior to activation for a command to be executed. |
Type: | STRING |
Status: | Read/Write |
Prior to activating an Inspector object, you must specify the command that
you want to be executed. Valid commands and their arguments are:
HexDump [MemoryID] [Length]
ListObjects
ListMemory
ListResources [ObjectID]
MemoryInfo [MemoryID]
SetField [ObjectID] [Name] [Value]
TextDump [MemoryID] [Length]
View [ObjectID]
Quit
More information on each command can be obtained by using 'help'. If an
invalid command is used then an error will be printed when the Inspector
object is activated.
|
|
Field: | Output |
Short: | Set this field to the object that is to receive Inspector's output. |
Type: | OBJECTID |
Status: | Read/Write |
The Output field must be set in order for an Inspector object to process
the commands and output them to the user. If this field is not set then
commands will not be executed when the Inspector object is Activated.
The Output object must accept text-based information via data channels
in order for the data to be interpreted correctly. If the Output object
does not support text based information, the Inspector object will still
process the command but the user will not receive any text based output.
It is recommended that this field points to an object that is a member
of the TextList class.
|
|
Field: | Quit |
Short: | If Inspector is used as an application, point this field to the application's window. |
Type: | OBJECTID |
Status: | Read/Write |
When the 'quit' command is used, the default action for an Inspector
object is for it to self-destruct. This can be undesirable, and a more
appropriate reaction may be to destroy the application window that contains
the Inspector object.
By setting this field, you will force the Inspector object to free the
external reference when the 'quit' command is used.
|
|