NPL::CNPLRuntime Class Reference

Collaboration diagram for NPL::CNPLRuntime:

[legend]List of all members.

---

Detailed Description

CNPLRuntime is a wrapper of the NPL application programming interface (NPL API).

it is normally used as a singleton class.

Public Member Functions
	CNPLRuntime (void)
	command line: local="config/local.ini"
void	Init ()
	initialize NPL runtime environment
void	Cleanup ()
	clean up the NPL runtime environment
NeuronFile *	GetNeuronFile (const char *filePath)
	Get local neuron File by file path.
NeuronFile *	CreateNeuronFile (const char *filePath)
	Get local neuron File by file path.
bool	DeleteNeuronFile (const char *filePath)
	release and delete a given neuron file's run time environment.
void	DoNeuronSCode (NeuronFile *pFile, const char *sCall, int nLength=0)
	execute a script code immediately, in the specified neuron file runtime.
void	DoNeuronSCode (const char *filePath, const char *sCall, int nLength=0)
	execute a script code immediately, in the specified neuron file runtime.
int	ActivateNeuronFile (const char *sNeuronFile, const char *code)
	Activate a given neuron file.
void	DoFile (const char *sNeuronFile, const char *sFilename)
	Do the content of a given file.
void	DoFile (NeuronFile *sNeuronFile, const char *sFilename)
::ParaEngine::INPLJabberClient *	GetJabberClient (const char *sJID)
	get an existing jabber client instance interface by its JID.
::ParaEngine::INPLJabberClient *	CreateJabberClient (const char *sJID)
	Create a new jabber client instance with the given jabber client ID.
bool	CloseJabberClient (const char *sJID)
	close a given jabber client instance.
void	AsyncDownload (const char *url, const char *destFolder, const char *callbackScript, const char *DownloaderName)
	Asynchronously download a file from the url.
void	CancelDownload (const char *DownloaderName)
	cancel all asynchronous downloads that matches a certain downloader name pattern
int	Download (const char *url, const char *destFolder, const char *callbackScript, const char *DownloaderName)
	Synchronous call of the function AsyncDownload().
void	Run (bool bToEnd=true)
	call this function regularly, to process packages.
const char *	GetFileName ()
	get current file name which is being processed now.
void	NPL_AddDNSRecord (const char *sDNSName, const char *sAddress)
	add a DNS server record to the current NPL runtime.
void	NPL_LoadFile (const char *filePath, bool bReload)
	load a new glia file (in the local environment) without running it.
void	LoadFile (lua_State *L, const char *filePath, bool bReload)
	load file in the given lua_state.
void	NPL_Activate (const char *sNeuronFile, const char *code=NULL, int channel=0, int priority=2, int reliability=3)
	activate the specified file.
void	NPL_Activate (const NPLFileName &FullName, const char *code=NULL, int channel=0, int priority=2, int reliability=3)
void	NPL_SetDefaultChannel (int channel_ID)
	Set the default channel ID, default value is 0.
int	NPL_GetDefaultChannel ()
	Get the default channel ID, default value is 0.
void	NPL_SetChannelProperty (int channel_ID, int priority, int reliability)
	Messages can be sent via predefined channels.
void	NPL_ResetChannelProperties ()
	reset all 16 predefined channel properties.
void	NPL_GetChannelProperty (int channel_ID, int *priority, int *reliability)
	see also NPL_SetChannelProperty
void	NPL_RegisterWSCallBack (const char *sWebServiceFile, const char *sCode)
	this method will associate a web service (method) with either a sCode, which will be called when the web service returned.
void	NPL_UnregisterWSCallBack (const char *sWebServiceFile)
	unregister web service call back for a given file.
bool	NPL_SetTimer (int nIDEvent, float fElapse, const char *sNeuronFile)
	creates a timer with the specified time-out value
bool	NPL_KillTimer (int nIDEvent)
	Destroys the specified timer.
bool	NPL_ChangeTimer (int nIDEvent, int dueTime, int period)
	Changes the start time and the interval between method invocations for a timer, using 32-bit signed integers to measure time intervals.
void	NPL_EnableNetwork (bool bEnable, const char *CenterName, const char *password)
	Enable the network, by default the network layer is disabled.
const string &	NPL_GetSourceName ()
	get the current activation's source name.
void	NPL_SetSourceName (const char *sName)
	Set the current activation's source name.
int	DoString (lua_State *L, const char *sCall, int nLength=0)
	do string in the given runtime.
Static Public Member Functions
static CNPLRuntime *	GetInstance ()
	the singleton instance
static INPLStimulationPipe *	GetNetworkLayerPipe ()
	Get the network layer pipe.
static const string &	NPL_GetSourceNameS ()
static void	NPL_SetSourceNameS (const char *sName)
static void	NPL_AddDNSRecordS (const char *sDNSName, const char *sAddress)
static void	NPL_LoadFileS (const char *filePath, bool bReload)
static void	NPL_ActivateS (const char *sNeuronFile, const char *code, int channel=0, int priority=2, int reliability=3)
static bool	NPL_SetTimerS (int nIDEvent, float fElapse, const char *sNeuronFile)
static bool	NPL_KillTimerS (int nIDEvent)
static void	NPL_DoStringS (const char *sCode)
static int	NPL_DoGliaFile (const char *filename, const char *sCall=NULL)

---

Member Function Documentation

void CNPLRuntime::Init

(

)

initialize NPL runtime environment

Load glia file's default runtime library

void CNPLRuntime::Cleanup

(

)

clean up the NPL runtime environment

destroy the glia runtime state

clean up loaded glia file items

clean up other runtime states

clean up loaded neuron files

clear DNS stack

clear file name stack

NeuronFile * CNPLRuntime::GetNeuronFile

(

const char *

filePath

)

Get local neuron File by file path.

Parameters:

filePath,:

the local file path in the following format: [dir0]/[dir1]/[dir2]/[filename.lua]

Returns:

: return the NeuronFile reference. If the file is not found, return NULL.

NeuronFile * CNPLRuntime::CreateNeuronFile

(

const char *

filePath

)

Get local neuron File by file path.

If the neuron file does not exist, it will be created.

Parameters:

filePath,:

the local file path in the following format: [dir0]/[dir1]/[dir2]/[filename.lua]

Returns:

: return the NeuronFile reference. If the file is not found, return NULL.

load the neuron file and build its runtime state if it has not.

Load and execute the a buffer of code in protected mode ( lua_pcall() ) Output messages through log interface

bool CNPLRuntime::DeleteNeuronFile

(

const char *

filePath

)

release and delete a given neuron file's run time environment.

It will cause the GetNeuronFile function to return false.

void CNPLRuntime::DoNeuronSCode	(	NeuronFile *	pFile,
		const char *	sCall,
		int	nLength = 0
	)

execute a script code immediately, in the specified neuron file runtime.

Parameters:

	pFile,:	the file to execute
	sCall,:	the string to executed.
	nLength,:	sCall string length. In case it comes from a file, we can know it in advance

Note:

: if this is 0, length will be calculated, but must be smaller than a predefined safe length. If this is positive. any string length is allowed.

void CNPLRuntime::DoNeuronSCode	(	const char *	filePath,
		const char *	sCall,
		int	nLength = 0
	)

execute a script code immediately, in the specified neuron file runtime.

Parameters:

	pFile,:	the file to execute
	sCall,:	the string to executed.
	nLength,:	sCall string length. In case it comes from a file, we can know it in advance.

Note:

: if this is 0, length will be calculated, but must be smaller than a predefined safe length. If this is positive. any string length is allowed.

int CNPLRuntime::ActivateNeuronFile	(	const char *	sNeuronFile,
		const char *	code
	)

Activate a given neuron file.

The neuron file will be loaded first if it has not.

Parameters:

sNeuronFile,:

the local file path.

Returns:

: return 1 if succeed, or 0 if failed. the error message is currently written to log file.

activate the neuron file

first call the global activate() function if there is one.

void CNPLRuntime::DoFile	(	const char *	sNeuronFile,
		const char *	sFilename
	)

Do the content of a given file.

Call this multiple times will do the file multiple times. It is very similar to NPL.Load(sFileName, true)

Parameters:

	sNeuronFile,:	in which runtime environment to do the file, it can be nil or "", which is the glia file environment, or it can be a neuron file name.
	sFilename,:	file name.

Remarks:

:caution: there may be a security issue.

ParaEngine::INPLJabberClient * CNPLRuntime::GetJabberClient

(

const char *

sJID

)

get an existing jabber client instance interface by its JID.

If the client is not created using CreateJabberClient() before, function may return NULL.

Parameters:

sJID,:

such as "lixizhi@paraweb3d.com"

ParaEngine::INPLJabberClient * CNPLRuntime::CreateJabberClient

(

const char *

sJID

)

Create a new jabber client instance with the given jabber client ID.

It does not open a connection immediately.

Parameters:

sJID,:

such as "lixizhi@paraweb3d.com"

bool CNPLRuntime::CloseJabberClient

(

const char *

sJID

)

close a given jabber client instance.

Basically, there is no need to close a web service, unless one wants to reopen it with different credentials

Parameters:

sJID,:

such as "lixizhi@paraweb3d.com"

void CNPLRuntime::AsyncDownload	(	const char *	url,
		const char *	destFolder,
		const char *	callbackScript,
		const char *	DownloaderName
	)

Asynchronously download a file from the url.

Parameters:

callbackScript,:

script code to be called, a global variable called msg is assigned, as below msg = {DownloadState=""|"complete"|"terminated", totalFileSize=number, currentFileSize=number, PercentDone=number}

void CNPLRuntime::CancelDownload

(

const char *

DownloaderName

)

cancel all asynchronous downloads that matches a certain downloader name pattern

Parameters:

DownloaderName:regular

expression. such as "proc1", "proc1.*", ".*"

int CNPLRuntime::Download	(	const char *	url,
		const char *	destFolder,
		const char *	callbackScript,
		const char *	DownloaderName
	)

Synchronous call of the function AsyncDownload().

This function will not return until download is complete or an error occurs. this function is rarely used. AsyncDownload() is used.

Returns:

:1 if succeed, 0 if fail

void CNPLRuntime::Run

(

bool

bToEnd = true

)

call this function regularly, to process packages.

Parameters:

bToEnd,:

if true, the function will only return when there is no more input packages in the queue

activate all timers

process results from NPL web service client

read from the NPL network layer

the Neuron file activation

the glia file activation

IMPORTANT: we are responsible to delete the packet.

const char * CNPLRuntime::GetFileName

(

)

get current file name which is being processed now.

void CNPLRuntime::NPL_AddDNSRecord	(	const char *	sDNSName,
		const char *	sAddress
	)

add a DNS server record to the current NPL runtime.

DNS server record is a mapping from name to (IP:port) if one maps several IP:port to the same name, the former ones will be overridden.

Parameters:

	sDNSName,:	the DNS server name. the DNS name "_world" is used for the current world DNS server. It is commonly used as a DNS reference to the current world that the user is exploring.
	sAddress,:	"IP:port". e.g. "192.168.1.10:4000"

TODO: add security: we cannot allow every one to change this as they wish. The user must be informed before this can be changed.

void CNPLRuntime::NPL_LoadFile	(	const char *	filePath,
		bool	bReload
	)

load a new glia file (in the local environment) without running it.

If the glia file is already loaded, it will not be loaded again. If the file extension is ".dll", it will be treated as a plug-in. if the filepath is "*.dll", it means all DLLs in that directory. IMPORTANT: unlike other activation functions, this is more like "include()", the function will be loaded where it is and returned to the original caller upon finishing.

Parameters:

	filePath,:	the local file path
	bReload,:	if true, the file will be reloaded even if it is already loaded. otherwise, the file will only be loaded if it is not loaded yet.

Returns:

: return the GliaFile reference.

void CNPLRuntime::LoadFile	(	lua_State *	L,
		const char *	filePath,
		bool	bReload
	)

load file in the given lua_state.

Parameters:

L,:

if this is NULL, it means glia file.

create the activate table, if it does not exist

the activation function is stored in __files global variable, indexed by the the file name. There activation function may be nil.

get the "__files" global table in the runtime

get activation function of the file name

void CNPLRuntime::NPL_Activate	(	const char *	sNeuronFile,
		const char *	code = NULL,
		int	channel = 0,
		int	priority = 2,
		int	reliability = 3
	)

activate the specified file.

It can either be glia file or neuron file. and it can either be local or using the default or specified DNS. All these information is extracted from the sNeuronFile parameters.

Parameters:

sNeuronFile,:

Neuron File name for this neuron file. It may contain activation type, namespace or DNS server information. They should be specified in the following format. If the file extension is ".dll", it will be treated as a plug-in dll. [(g|gl|l)] [ namespace : ] relative_path [ @ DNSServerName ] the following is a list of all valid file name combinations: "NPC:NPL/CreatureA.lua@world" -- neuron file with "NPL" namespace and a specified DNS "NPC:NPL/CreatureA.lua" -- neuron file with "NPL" namespace and local DNS "NPL/CreatureA.lua" -- neuron file with default "NPL"(the first directory name) namespace and local DNS "(g)NPL/CreatureA.lua" -- glia file, which will be sent to UI receivers and activated from there. So one can think of the content of glia file as a bunch of UI functions. "(gl)NPL/CreatureA.lua" -- glia file forcing local activation: which will omit UI receivers and activate from local environment. "(l)NPL/CreatureA.lua" -- local neuron file: which uses no namespace and no DNS, it is just treated as a local neuron file. "http://paraengine.com/login.aspx" -- a web service URL. see also NPL.RegisterWSCallBack();

the "g|l" in the parenthesis denotes activation type. "g" is short for glia file. and "l" is short for local. if nothing is specified, it means neuron file. Both the neuron file and glia file can be local. A local file is always selected in the local NPL environment and execute from there. Currently, one can not specify namespace or DNS for glia file, they are always selected from the local NPL runtime environment.

If there is no namespace specified, the first directory path is used as the namespace. e.g "NPC:NPL/CreatureA.lua" is equivalent to "NPL/CreatureA.lua" NOTE: if relative_path contains "\\", it will be converted to "/".

Parameters:

	code,:	it is a chunk of code that should be executed in the destination neuron. this code usually set the values of POL global variables.
	channel:On	which channel to send the package. It can be a number in [0,15]. In case it is nil, the default channel (usually 0) is used.
	priority,:	From high to low.If this is nil, SYSTEM_PRIORITY(0) is used. following enumerations are used to describe when packets are delivered. enum PacketPriority { SYSTEM_PRIORITY, /// internally Used to send above-high priority messages. HIGH_PRIORITY, /// High priority messages are send before medium priority messages. MEDIUM_PRIORITY, /// Medium priority messages are send before low priority messages. LOW_PRIORITY, /// Low priority messages are only sent when no other messages are waiting. };
	reliability:From	unreliable to reliable sequenced. 0 stands for unreliable. If this is nil, RELIABLE_ORDERED(3) is used. following enumerations are used to describe how packets are delivered. enum PacketReliability { UNRELIABLE, /// Same as regular UDP, except that it will also discard duplicate datagrams. It adds (6 to 17) + 21 bits of overhead, 16 of which is used to detect duplicate packets and 6 to 17 of which is used for message length. UNRELIABLE_SEQUENCED, /// Regular UDP with a sequence counter. Out of order messages will be discarded. This adds an additional 13 bits on top what is used for UNRELIABLE. RELIABLE, /// The message is sent reliably, but not necessarily in any order. Same overhead as UNRELIABLE. RELIABLE_ORDERED, /// This message is reliable and will arrive in the order you sent it. Messages will be delayed while waiting for out of order messages. Same overhead as UNRELIABLE_SEQUENCED. RELIABLE_SEQUENCED /// This message is reliable and will arrive in the sequence you sent it. Out or order messages will be dropped. Same overhead as UNRELIABLE_SEQUENCED. };

void CNPLRuntime::NPL_SetDefaultChannel

(

int

channel_ID

)

Set the default channel ID, default value is 0.

Default channel is used when NPL.activate() call¡¯s does not contain the channel property.

Parameters:

channel_ID

It can be a number in [0,15].default is 0

int CNPLRuntime::NPL_GetDefaultChannel

(

)

Get the default channel ID, default value is 0.

Default channel is used when NPL.activate() call¡¯s does not contain the channel property.

Returns:

channel_ID It can be a number in [0,15].default is 0

void CNPLRuntime::NPL_SetChannelProperty	(	int	channel_ID,
		int	priority,
		int	reliability
	)

Messages can be sent via predefined channels.

There are 16 channels from 0 to 15 to be used. 0 is the default channel. This method sets the channel property for a given channel. The default channel property is given in table. The following table shows the default NPL channel properties. It is advised for users to stick to this default mapping when developing their own applications. Table 1. Default NPL channel properties channel_ID Priority Reliability Usage 0 med RELIABLE_ORDERED System message 1 med UNRELIABLE_SEQUENCED Character positions 2 med RELIABLE_ORDERED Large Simulation Object transmission, such as terrain height field. 4 med RELIABLE_ORDERED Chat message 14 med RELIABLE files transmission and advertisement 15 med RELIABLE_SEQUENCED Voice transmission 11-15 med RELIABLE_ORDERED

Parameters:

	channel_ID
	priority
	reliability

void CNPLRuntime::NPL_ResetChannelProperties

(

)

reset all 16 predefined channel properties.

according to table1. Default NPL channel properties. see also NPL_SetChannelProperty The following table shows the default NPL channel properties. It is advised for users to stick to this default mapping when developing their own applications. Table 1. Default NPL channel properties channel_ID Priority Reliability Usage 0 med RELIABLE_ORDERED System message 1 med UNRELIABLE_SEQUENCED Character positions 2 med RELIABLE_ORDERED Large Simulation Object transmission, such as terrain height field. 4 med RELIABLE_ORDERED Chat message 14 med RELIABLE files transmission and advertisement 15 med RELIABLE_SEQUENCED Voice transmission 11-15 med RELIABLE_ORDERED

void CNPLRuntime::NPL_GetChannelProperty	(	int	channel_ID,
		int *	priority,
		int *	reliability
	)

see also NPL_SetChannelProperty

Parameters:

	channel_ID
	priority	[out]
	reliability	[out]

void CNPLRuntime::NPL_RegisterWSCallBack	(	const char *	sWebServiceFile,
		const char *	sCode
	)

this method will associate a web service (method) with either a sCode, which will be called when the web service returned.

The returned message, if any, will be passed via a global parameter called msg. For example: Function callbackFunc1() If(msg.username~=nil) then end End NPL.RegisterWSCallBack("http://paraengine.com/login.aspx",callbackFunc1); NPL.activate("http://paraengine.com/login.aspx", {username=¡±lxz¡±});

Parameters:

	sWebServiceFile	URL of the web service
	sCode	code to be executed when the web service is called. When a two-way web service call is invoked; it internally will create a thread for the returning message. Please refer to .Net 3.0 network communication architecture.

void CNPLRuntime::NPL_UnregisterWSCallBack

(

const char *

sWebServiceFile

)

unregister web service call back for a given file.

Parameters:

sWebServiceFile

if this is nil or "", all call backs will be unregistered.

bool CNPLRuntime::NPL_SetTimer	(	int	nIDEvent,
		float	fElapse,
		const char *	sNeuronFile
	)

creates a timer with the specified time-out value

Parameters:

	nIDEvent,:	Specifies a positive timer identifier. For nIDEvent<=0, they are reserved for internal uses. If the NPL runtime already has a timer with the value nIDEvent, then the existing timer is replaced by the new timer. When SetTimer replaces a timer, the timer is reset.
	fElapse,:	Specifies the time-out value, in seconds. Please note that a timer will not be repeatedly activated if its timeout is shorter than the frame rate of the NPL simulation pipeline .
	sNeuronFile,:	The NPL file to be activated when the time-out value elapses. For more information about the file name See NPL.activate().

Returns:

: true if succeeds.An application can pass the value of the nIDEvent parameter to the NPL.KillTimer function to destroy the timer.

bool CNPLRuntime::NPL_KillTimer

(

int

nIDEvent

)

Destroys the specified timer.

Parameters:

nIDEvent,:

Specifies the timer to be destroyed.For nIDEvent<=0, they are reserved for internal uses can not be killed by this function. This value must be the same as the nIDEvent value passed to the SetTimer function that created the timer.

Returns:

: If the function succeeds, the return value is true

bool CNPLRuntime::NPL_ChangeTimer	(	int	nIDEvent,
		int	dueTime,
		int	period
	)

Changes the start time and the interval between method invocations for a timer, using 32-bit signed integers to measure time intervals.

Parameters:

	nIDEvent,:	Specifies the timer to be destroyed.For nIDEvent<=0, they are reserved for internal uses can not be killed by this function. This value must be the same as the nIDEvent value passed to the SetTimer function that created the timer.
	dueTime,:	The amount of time to delay before the invoking the callback method specified when the Timer was constructed, in milliseconds. Specify zero (0) to restart the timer immediately. however, the current implementation does not accept dueTime that is larger than MAX_TIMER_DUE_TIME 10000000, which is 10000 seconds.
	period:The	time interval between invocations of the callback method specified when the Timer was constructed, in milliseconds.

Returns:

: If the function succeeds, the return value is true

void CNPLRuntime::NPL_EnableNetwork	(	bool	bEnable,
		const char *	CenterName,
		const char *	password
	)

Enable the network, by default the network layer is disabled.

calling this function multiple time with different CenterName will restart the network layer with a different center name.

Parameters:

	bEnable	true to enable, false to disable.If this is false, the CenterName and Password are ignored.
	CenterName	the local nerve center name. it is also the user name which local receptor will use in the credentials to login in other NPL runtime.
	Password

Returns:

true if succeeded.

static INPLStimulationPipe* NPL::CNPLRuntime::GetNetworkLayerPipe

(

)

[static]

Get the network layer pipe.

Returns:

: INPLStimulationPipe* m_pNetPipe

const string& NPL::CNPLRuntime::NPL_GetSourceName

(

)

get the current activation's source name.

Each NPL activation has a source name which started the activation. This is usually "" for local activation and some kind of "name@server" for network activation.

void NPL::CNPLRuntime::NPL_SetSourceName

(

const char *

sName

)

Set the current activation's source name.

Each NPL activation has a source name which started the activation. This function is called automatically when a new activation occurs.So only call this function if one wants to override the old one for special code logics.

Parameters:

sName

This is usually "" for local activation and some kind of "name@server" for network activation.

int CNPLRuntime::DoString	(	lua_State *	L,
		const char *	sCall,
		int	nLength = 0
	)

do string in the given runtime.

This function is usually called from the scripting interface.

Parameters:

	L,:	the runtime environment. It can be NULL where the glia file is used.
	sCall,:	the string to executed.
	nLength,:	length in bytes.if this is 0, length will be calculated, but must be smaller than a predefined safe length. If this is positive. any string length is allowed.

do sCall as a string Assume caller is authorized, since it is from the local environment. This may lack security, and is only valid for authorized callers.

Load and execute the a buffer of code in protected mode ( lua_pcall() ) Output messages through log interface

---