current stable: 0.99.6 unstable: cvs (0.99.7) |
||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Chapter 5. Native Modules - By HandThe aim of this chapeter is to combine information given in the previous chapters, add some more insight and show you how to write modules by hand. This chapter is also very useful for people wanting to embed ferite as it shows how to export an API by hand. FunctionsFunctions are as easy to write by hand as they are with builder. Infact, builder simply makes the following completely automatic, which is good 95% of the time, but sometimes you just have to take complete controll. As with normal C functions we have to declare our native ferite functions. This is done in three stages, first we declare it, then we create our FeriteFunction structure and then we register it with the ferite engine. To declare the variable, you use the macro FE_NATIVE_FUNCTION, this is true for both object/class methods and normal namespace functions. This takes one argument, which is the name of the function you wish to create. After the macro, you simply write the body of your function as you normally would. For example:
That is as simple as the functions are going to get. The next thing we need to do is create a FeriteFunction structure with which we can register the function [using the functions mentioned in the last chapter]. This is also easy, it is simply a function call to ferite_create_external_function. It's prototype is below:
This takes the current script, the name of the function, a pointer to the function, and it's signiture description. The first two are fairly obvious. The third means you simply pass the name of the native function, eg. in the above example it would be printfnc. The description is slightly more complicated, it is a null terminated string which takes a number of characters that describe what arguments the function can take.
Each character responds to each type and it allows ferite to make sure that the function gets passed the correct parameters. To make life slighty clearer, here are a few examples with the ferite function and what would be the equivelent description for a native function:
To register the function you have back, you either use ferite_register_ns_function or ferite_register_class_function. You must be aware that you can only register each created function once! Otherwise ferite will certainly die when it tries to clean everything up at the end of execution. So, lets assume that our above print function takes a string and a number and prints out the string the number of times it is told. The example below will show how to declare, create a FeriteFunction and register it in a namespace. The example will also allow us to touch on another couple of important areas.
Point #1 is the main point to be covered. ferite_get_parameters is a helper function for getting the values of the parameters you have passed into C variables you can manipulate. It is very important that you do not delete or free the values you have because they point to the real values. This function takes two arguments at a minimum and any number of arguments more, the first is the parameter list you are given, when writing the native function, it is always called params. The second argument is the number of values from the parameter list that you want, and the rest of the arguments are pointer to the variables you wish to set. In our example above, the address of the print and countd variables were passed. This is exactly how builder gets the values from the parameter list - it is simply hidden from the programmer. Point #2 is just a highlight of a point made before. All functions must return something even if it is just a void. Builder hides point #2 from you, but when writing functions from scratch, it is important you remember to return something. To get the number of parameters that where passed to the function, you can use the ferite_get_parameter_count, this takes just one argument [params] and returns the number of variables in it.
When you have a method within an object there are always two extra parameters. self and super. To get at the object which self points to, you have to get at it the same way you do other variables. The example below is almost identical to the one above except it assumes printfnc is part of an object.
So there we have it. How to write a function, it is not really that hard once you know how.
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||
ferite et al © 2000-2004, Chris Ross |