Appendices: Extending SMILE.NET Library
From DSL
Why to Extend the Library
Sometimes it may be desirable to have a set of functionalities encapsulated inside a single method. These functionalities can be later executed on a batch basis by a single method call. A solution would be to derive a custom class from the SMILE.NET Network class in C# or VB.NET (or even Managed C++ if a need be).
There are situations, however, when an access to the "low level" SMILE interface would be desired. A performance concern could serve as a quite good an argument for that. In that case sources of SMILE.NET can be modified, and that is what is covered below.
The library is written using Managed C++. The Network class itself has a private member net being a reference to an original SMILE DSL_Network object. This object gives a full access to the network.
What is and What is Not Covered Below
We will not make a step-by-step tutorial. Some obvious shortcuts will be made. This tutorial is not meant to address the needs of novice users.
We will henceforth assume that you will be using Visual Studio .NET 2003 (version 7.1) to open the SMILE.NET project from the SMILE.NET package.
Adding a New Method
Step 1: Implementing the Method's Body
Suppose we want to add a method which would create a file with a network having only a root node.
int CreateRootNetwork(String *rootName, String *fileName) {
int res = net->AddNode(DSL_CPT, rootName);
if (res != DSL_OUT_OF_RANGE)
res = net->WriteFile(fileName, DSL_XDSL_FORMAT);
return res;
}
Step 2: Building the Project
Obviously a modified project has to be rebuild.
Step 3: Using the Method
It takes nothing more than copying the freshly built library (smilenet.dll) to our application folder and making use of our new method. If we wanted to use it in a sample C# application provided with the SMILE.NET package, we would add the following lines:
Network net = new Network();
int res = net.CreateRootNetwork("root", "network.xdsl");
Helpful SMILE.NET Methods
The library contains several private functions which facilitate the process of extending it. The three most important ones are described below (all are methods in the Network class).
DSL_node *ValidateNodeHandle(int handle)
Takes a node's handle to return a pointer to the original SMILE DSL_node structure. This method should be used always a user's input in a form of node's handle is expected. If an invalid handle is provided an exception is thrown.
- int ValidateNodeId(String *nodeId)
Takes a node's id to return its handle. This method should be used always when a user's input in a form of node's handle is expected. If an invalid is provided an exception is thrown.
This method is used to create a variant of a method which is expecting a node's handle - a one which expects an id instead. It is used throughout SMILE.NET to give a user a choice of what they would prefer to use - a handle or an id. SMILE.NET has more of that kind of "symmetry supporting" functions. Compare following:
- int ValidateOutcomeId(int nodeHandle, String *outcomeId)
- int ValidateParentId(int nodeHandle, String *parentId)
- String *HandlesToIds(DSL_intArray& native)__gc[]
Takes an array of nodes' handles to return an array of their ids.
- void ValidateId(String *id)
Checks if a specified id is valid. If it is invalid, an exception is thrown.
Just as a reminder, a valid id has to start with a letter and can contain only letters, digits and underscores.
Useful Links
