ref object

Path: /sdk/add_on/scripthandle/

The ref type is a generic container that can hold any handle. It is a value type, but behaves very much like an object handle.

The type is registered with RegisterScriptHandle(asIScriptEngine*).

See also

Registering a generic handle type

Public C++ interface

class CScriptHandle 
{
public:
  // Constructors
  CScriptHandle();
  CScriptHandle(const CScriptHandle &other);
  CScriptHandle(void *ref, int typeId);
  ~CScriptHandle();
 
  // Copy the stored reference from another handle object
  CScriptHandle &operator=(const CScriptHandle &other);
  
  // Set the reference
  void Set(void *ref, asITypeInfo *type);
 
  // Compare equalness
  bool operator==(const CScriptHandle &o) const;
  bool operator!=(const CScriptHandle &o) const;
  bool opEquals(void *ref, int typeId) const;
 
  // Dynamic cast to desired handle type
  void Cast(void **outRef, int typeId);
 
  // Returns the type of the reference held
  asITypeInfo   *GetType() const;
  int            GetTypeId() const;
  
  // Returns the reference
  void *GetRef();
};

Public script interface

See also

ref in the script language

Example usage from C++

Even though the CScriptHandle is a value type, when registering properties of its type they should be registered as handles. The same goes for function arguments and return types.

CScriptHandle g_handle;
 
void Function(CScriptHandle handle)
{
  ... use the methods of CScriptHandle to determine the true object held in it
}
 
void Register(asIScriptEngine *engine)
{
  int r;
  r = engine->RegisterGlobalProperty("ref @g_handle", &g_handle); assert( r >= 0 );
  r = engine->RegisterGlobalFunction("void Function(ref @)", asFUNCTION(Function), asCALL_CDECL); assert( r >= 0 );
}

To set an object pointer in the handle from the application, you'll use the Set() method passing a pointer to the object and the type of the object.

To retrieve an object pointer from the application you'll use the Cast() method passing in a pointer to the pointer and the wanted type id. If the type id given doesn't match the stored handle the returned pointer will be null.

To retrieve an object of an unknown type use the GetType() or GetTypeId() to determine the type stored in the handle, then use the Cast() method.

Example on how to return a newly registered function from C++

The following is a bit more practical example of using the CScriptHandle to return a recently registered function. The function could for example have been loaded from a shared library, based on informed function and name from the script.

// This C++ function would be called from script, register a new C++ function and then return it to the script as a function pointer
// Register with engine->RegisterGlobalFunction("ref @getDynamicFunction()", asFUNCTION(getDynamicFunction), asCALL_CDECL);
CScriptHandle getDynamicFunction()
{
  // Get the active context and engine to register the function with
  asIScriptContext* ctx = asGetActiveContext();
  asIScriptEngine *engine = ctx->GetEngine();
 
  // Register the function. The actual function could be dynamically loaded from a shared library
  int funcId = engine->RegisterGlobalFunction("void dynamicFunction()", asFUNCTION(dynamicFunction), asCALL_CDECL);
 
  // Create the CScriptHandle and put the function pointer in it for return to script
  asIScriptFunction* func = engine->GetFunctionById(funcId);
  CScriptHandle ref;
  ref.Set(func, engine->GetTypeInfoById(func->GetTypeId()));
 
  return ref;
}

In the script the this would be used in the following way:

  funcdef void func();
  void main()
  {
    // Get the function pointer as a generic ref
    ref @r = getDynamicFunction();

    // Cast the ref to the expected function pointer
    func @f = cast<func>(r);

    // Call the function
    f();
  }