PageRenderTime 17ms CodeModel.GetById 14ms app.highlight 1ms RepoModel.GetById 1ms app.codeStats 0ms

/xbmc/visualizations/Vortex/angelscript/docs/doxygen/source/doc_call_script_func.h

http://github.com/xbmc/xbmc
C++ Header | 192 lines | 0 code | 0 blank | 192 comment | 0 complexity | 878c10c92523784693f875ec4d6243cc MD5 | raw file
  1/**
  2
  3\page doc_call_script_func Calling a script function
  4
  5
  6\section doc_call_script_1 Preparing context and executing the function
  7
  8Normally a script function is executed in a few steps:
  9
 10<ol>
 11<li>Prepare the context
 12<li>Set the function arguments
 13<li>Execute the function
 14<li>Retrieve the return value
 15</ol>
 16
 17The code for this might look something like this:
 18
 19\code
 20// Get a script context instance. Usually you'll want to reuse a previously
 21// created instance to avoid the overhead of allocating the instance with
 22// each call.
 23asIScriptContext *ctx = engine->CreateContext();
 24
 25// Obtain the function id from the module. This value should preferrably  
 26// be cached if the same function is called multiple times.
 27int funcId = engine->GetModule(module_name)->GetFunctionIdByDecl(function_declaration);
 28
 29// Prepare() must be called to allow the context to prepare the stack
 30ctx->Prepare(funcId);
 31
 32// Set the function arguments
 33ctx->SetArgDWord(...);
 34
 35int r = ctx->Execute();
 36if( r == asEXECUTION_FINISHED )
 37{
 38  // The return value is only valid if the execution finished successfully
 39  asDWORD ret = ctx->GetReturnDWord();
 40}
 41
 42// Release the context when you're done with it
 43ctx->Release();
 44\endcode
 45
 46If your application allow the execution to be suspended, either by using
 47the callback function or registering a function that allow the script to 
 48manually suspend the execution, then the execution function may return 
 49before finishing with the return code asEXECUTION_SUSPENDED. In that case you
 50can later resume the execution by simply calling the execution function again.
 51
 52Note that the return value retrieved with GetReturnValue() is only valid
 53if the script function returned successfully, i.e. if Execute() returned 
 54asEXECUTION_FINISHED.
 55
 56\section doc_call_script_2 Passing and returning primitives
 57
 58When calling script functions that take arguments, the values of these 
 59arguments must be set after the call to Prepare() and before Execute(). 
 60The arguments are set using a group of SetArg methods:
 61
 62\code
 63int SetArgDWord(int arg, asDWORD value);
 64int SetArgQWord(int arg, asQWORD value);
 65int SetArgFloat(int arg, float value);
 66int SetArgDouble(int arg, double value);
 67\endcode
 68
 69<code>arg</code> is the argument number, where the first argument is on 0, the second 
 70on 1, and so on. <code>value</code> is the value of the argument. What method to use is 
 71determined by the type of the parameter. For primitive types you can use any of these. 
 72If the parameter type is a reference to a primitive type it is recommended to use the 
 73SetArgDWord() method and pass the pointer as the value. For non-primitive types the 
 74method SetArgObject() should be used, which will be described in the next section.
 75
 76\code
 77// The context has been prepared for a script 
 78// function with the following signature:
 79// int function(int, double, int&in)
 80
 81// Put the arguments on the context stack, starting with the first one
 82ctx->SetArgDWord(0, 1);
 83ctx->SetArgDouble(1, 3.141592);
 84int val;
 85ctx->SetArgDWord(2, (asDWORD)&val);
 86\endcode
 87
 88Once the script function has been executed the return value is retrieved in 
 89a similar way using the group of GetReturn methods:
 90
 91\code
 92asDWORD GetReturnDWord();
 93asQWORD GetReturnQWord();
 94float   GetReturnFloat();
 95double  GetReturnDouble();
 96\endcode
 97
 98Note that you must make sure the returned value is in fact valid, for 
 99example if the script function was interrupted by a script exception the value
100would not be valid. You do this by verifying the return code from Execute() or
101GetState(), where the return code should be asEXECUTION_FINISHED.
102
103\section doc_call_script_3 Passing and returning objects
104
105Passing registered object types to a script function is done in a similar
106way to how primitive types are passed. The function to use is SetArgObject():
107
108\code
109int SetArgObject(int arg, void *object);
110\endcode
111
112<code>arg</code> is the argument number, just like the other SetArg methods. 
113<code>object</code> is a pointer to the object you wish to pass.
114
115This same method is used both for parameters passed by value and for those
116passed by reference. The library will automatically make a copy of the object
117if the parameter is defined to be passed by value.
118
119\code
120// The complex object we wish to pass to the script function
121CObject obj;
122
123// Pass the object to the function
124ctx->SetArgObject(0, &obj);
125\endcode
126
127Getting an object returned by a script function is done in a similar way, using 
128GetReturnObject(): 
129
130\code
131void *GetReturnObject();
132\endcode
133
134This method will return a pointer to the object returned by the script function.
135The library will still hold a reference to the object, which will only be freed as 
136the context is released.
137
138\code
139// The object where we want to store the return value
140CObject obj;
141
142// Execute the function
143int r = ctx->Execute();
144if( r == asEXECUTION_FINISHED )
145{
146  // Get a pointer to the returned object and copy it to our object
147  obj = *(CObject*)ctx->GetReturnObject();
148}
149\endcode
150
151It is important to make a copy of the returned object, or if it is managed by 
152reference counting add a reference to it. If this is not done the pointer obtained 
153with GetReturnObject() will be invalidated as the context is released, or reused for 
154another script function call.
155
156\section doc_call_script_4 Exception handling
157
158If the script performs an illegal action, e.g. calling a method on a null handle, then
159the script engine will throw a script exception. The virtual machine will then abort
160the execution and the \ref asIScriptContext::Execute "Execute" method will return with the value
161\ref asEXECUTION_EXCEPTION.
162
163At this time it is possible to obtain information about the exception through the 
164\ref asIScriptContext's methods. Example:
165
166\code
167void PrintExceptionInfo(asIScriptContext *ctx)
168{
169  asIScriptEngine *engine = ctx->GetEngine();
170
171  // Determine the exception that occurred
172  printf("desc: %s\n", ctx->GetExceptionString());
173
174  // Determine the function where the exception occurred
175  int funcId = ctx->GetExceptionFunction();
176  const asIScriptFunction *function = engine->GetFunctionDescriptorById(funcId);
177  printf("func: %s\n", function->GetDeclaration());
178  printf("modl: %s\n", function->GetModuleName());
179  printf("sect: %s\n", function->GetScriptSectionName());
180  
181  // Determine the line number where the exception occurred
182  printf("line: %d\n", ctx->GetExceptionLineNumber());
183}
184\endcode
185
186If desired, it is also possible to \ref asIScriptContext::SetExceptionCallback "register a callback function" 
187that will be called at the moment the exception occurred, before the \ref asIScriptContext::Execute "Execute" method returns. 
188
189\see \ref doc_debug for information on examining the callstack
190
191
192*/