C++ Wrapper.md

Wrapper.md

C++ Wrapper API

This tries to outline what C++ API could be provided to the module writer. This might not be what the API at the border between the modules and the node binary is (which may look more like what is in the previous section) but would provide a more C++ friendly API>

All C/C++ methods will be passed a node::ni::ni_env object as part of their invocation. The ni_env object supports the following methods:

• getNIVersion();

• node::ni::ObjectHandle getGlobalObject()

• SetException(ObjectHandle)

• node::ni::ObjectHandle GetException()

• ClearException()

• NewBuffer(...)

• CopyBuffer(...)

• BufferFreeCallback(...)

New(...) (see description under Handle Objects)

Handle Objects

All parameters other than for the the methods on ni_env and the method node::ni::PrimitiveXXXX:Get() will be handle objects. The types of handle objects will include the following:

• PrimitiveStringHandle
• PrimitiveU32Handle
• ....
• ObjectHandle
• FunctionHandle
• PersistentHandle
• WeakHandle
• ScopeHandle

Primitive, Object and Function handle objects can be created using:

ni_env->New(...)

where the type of ... passed in determins the type of handle created as follows:

In (C/C++)	out
char*	node::ni:PrimitiveStringHandle
u32	node::ni::PrimitiveU32Handle
...
node:::ni::FunctionCallback	node::ni::FunctionHandle
node::ni::ObjectHandlenode	node::ni::ObjectHandle
nothing	node::ni::ObjectHandle (empty)
(Table is incomplete)

Primitive Handles

Primitive handles support the get() method which returns the C/C++ type in accordance with the type associatd with them as listed in the table above.

Object handles

For getting and setting properties Object handles support the following methods:

• Set(name, <PrimitiveHandle, ObjectHandle, or FunctionHandle>);
• Get(name)

The following methods are provided for creating persistem references:

• newPersistent(bool global, ObjectHandle)
• newWeak(ObjectHandle)

newPersistent will return a PersistentHandle. If gobal is specified as true then you cannot call the delete method on the handle returned.

newWeak will return a WeakHandle.

Function handles

The following methods are provided:

• ~delete()

Persistent handles

The following methods are provided:

• ~delete()

which indicates the persistent method can be removed.

Weak Handles

Weak handles provide the following methods:

node::ni::ObjectHandle get()

• ~delete();

ScopeHandles

Scope handles can be created by contructing an instance of

node::ni::newScope

Scope handles support the following methods:

• pop(ObjectHandle);
• ~delete()