ParaScripting::NPL Class Reference
[NPL]

List of all members.

---

Detailed Description

Neural Parallel Language functions are in this namespace.

Static Public Member Functions
static void	activate (const char *sNeuronFile, const object &sCode)
	activate the specified file.
static void	activate1 (const char *sNeuronFile)
static void	activate3 (const char *sNeuronFile, const object &sCode, int channel)
static void	activate5 (const char *sNeuronFile, const object &sCode, int channel, int priority, int reliability)
static void	activate2_ (const char *sNeuronFile, const char *sCode)
	this function is only called by .Net API.
static void	activate_ (const char *sNeuronFile, const char *sCode, int channel, int priority, int reliability)
	this function is only called by .Net API.
static void	call (const char *sNeuronFile, const object &sCode)
	This function is used to activate a local file synchronously.
static void	call_ (const char *sNeuronFile, const char *sCode)
	this function is only called by .Net API.
static const char *	GetFileName ()
	return the NPL file name that is being loaded.
static void	this_ (const object &funcActivate)
	NOTE: the function name is "this" in NPL, not "this_".
static void	load (const object &filePath, bool bReload)
	load a new glia file (in the local environment) without running it.
static void	load_ (const char *filePath, bool bReload)
	for NPL managed only.
static void	load1 (const object &filePath)
	same as NPL.load(filepath, false);
static void	EnableNetwork (bool bEnable, const char *CenterName, const char *password)
	Enable the network, by default the network layer is disabled.
static void	AddDNSRecord (const char *sDNSName, const char *sAddress)
	add a DNS server record to the current NPL runtime.
static bool	SetTimer (int nIDEvent, float fElapse, const char *sNeuronFile)
	creates a timer with the specified time-out value
static bool	KillTimer (int nIDEvent)
	Destroys the specified timer.
static bool	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.
static void	DoString (const object &sCode)
	execute a given string immediately in protected mode.
static void	DoString_ (const char *sCode)
	only for NPL managed only
static string	SerializeToSCode (const char *sStorageVar, const object &input)
	serialize a luabind object into sCode.
static bool	IsSCodePureData (const char *sCode)
	verify the script code.
static bool	IsPureData (const char *sCode)
	it will return true if input string is "false", "true", NUMBER, STRING, and {table}
static const char *	GetSourceName ()
	get the current activation's source name.
static void	SetSourceName (const char *sName)
	Set the current activation's source name.
static void	SetDefaultChannel (int channel_ID)
	Set the default channel ID, default value is 0.
static int	GetDefaultChannel ()
	Get the default channel ID, default value is 0.
static void	SetChannelProperty (int channel_ID, int priority, int reliability)
	Messages can be sent via predefined channels.
static void	ResetChannelProperties ()
	reset all 16 predefined channel properties.
static void	GetChannelProperty (int channel_ID, int *priority, int *reliability)
	see also NPL_SetChannelProperty
static void	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.
static void	UnregisterWSCallBack (const char *sWebServiceFile)
	unregister web service call back for a given file.
static void	AsyncDownload (const char *url, const char *destFolder, const char *callbackScript, const char *DownloaderName)
	Asynchronously download a file or an HTTP web page from the url.
static void	CancelDownload (const char *DownloaderName)
	cancel all asynchronous downloads that matches a certain downloader name pattern
static int	Download (const char *url, const char *destFolder, const char *callbackScript, const char *DownloaderName)
	Synchronous call of the function AsyncDownload().
static bool	CreateNeuronFile (const char *filePath)
	Get local neuron File by file path.
static bool	DeleteNeuronFile (const char *filePath)
	release and delete a given neuron file's run time environment.
static void	DoNeuronSCode (const char *filePath, const char *sCall)
	execute a script code immediately, in the specified neuron file runtime.
static void	DoFile (const char *sNeuronFile, const char *sFilename)
	Do the content of a given file.
static int	ActivateNeuronFile (const char *sNeuronFile, const char *code)
	Activate a given neuron file.
static void	Compile (const char *arguments)
	compile source The main advantages of precompiling chunks are: faster loading, protecting source code from accidental user changes, and off-line syntax checking.

---

Member Function Documentation

static void ParaScripting::NPL::activate	(	const char *	sNeuronFile,
		const object &	sCode
	)			[static]

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 the following is a list of all valid file name combinations: "all@local:network/client.lua" -- active network/client.lua neuron file on all users connected to the local center "username@local:network/client.lua" -- active network/client.lua neuron file for a connected user whose name is username "@server:network/server.lua" -- active network/server.lua neuron file on the latest connected remote server. This is usually used by a client to send a message to server. "(gl)NPL/CreatureA.lua" -- glia file forcing local activation: which will omit UI receivers and activate from local environment. "NPL/CreatureA.lua" -- identical to above; but it is highly advised that one use (gl) activation type qualifiers "(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. "(l)NPL/CreatureA.lua" -- local neuron file: which uses no namespace and no DNS, it is just treated as a local neuron file.

activation type qualifiers [(g|gl|l)]: 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 both g and l. 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.

namespace = [username]: namespace is a remote computer address known to the local NPL runtime.its format is similar to email address. To make a server name known to the local runtime, one needs to call ParaNetwork.AddNamespaceRecord() there are some namespace alias, which are replaced by their actual names. server name alias are "local" mapping to the local NPL runtime, "server" mapping to the most recently connected remote NPL runtime; "all" is a username alias represent all connected users at a server. such as "all@local", "@server", "user1@myserver" are all valid namespace name.

Obsolete rule:DO NOT USE: 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:

sCode,:

If it is a string, it is regarded as a chunk of code that should be executed in the destination neuron file's runtime. If this is a table or number, it will be transmitted via a internal variable called "msg". When activating neurons on a remote network, only pure data table is allowed in the sCode.

Note:

: pure data table is defined as table consisting of only string, number and other table of the above type. NPL.activate function also accepts ParaFileObject typed message data type. ParaFileObject will be converted to base64 string upon transmission. There are size limit though of 10MB. one can also programmatically check whether a script object is pure date by calling NPL.SerializeToSCode() function. Please note that data types that is not pure data in sCode will be ignored instead of reporting an error.

static void ParaScripting::NPL::activate2_	(	const char *	sNeuronFile,
		const char *	sCode
	)			[static]

this function is only called by .Net API.

static void ParaScripting::NPL::activate_	(	const char *	sNeuronFile,
		const char *	sCode,
		int	channel,
		int	priority,
		int	reliability
	)			[static]

this function is only called by .Net API.

static void ParaScripting::NPL::call	(	const char *	sNeuronFile,
		const object &	sCode
	)			[static]

This function is used to activate a local file synchronously.

Use activate() if you need an asynchronous activation. for more information, please see activate();

static void ParaScripting::NPL::call_	(	const char *	sNeuronFile,
		const char *	sCode
	)			[static]

this function is only called by .Net API.

static const char* ParaScripting::NPL::GetFileName

(

)

[static]

return the NPL file name that is being loaded.

Only call this function when the file is being initialized. i.e. at the root level. Note: calling this function inside other functions will lead to unexpected result.

static void ParaScripting::NPL::this_

(

const object &

funcActivate

)

[static]

NOTE: the function name is "this" in NPL, not "this_".

associate a user defined function as the activation function of this file. add the current file name to the __act table. create the activate table, if it does not exist.

Parameters:

funcActivate,:

the function pointer to the activation function. It can either be local or global.

static void ParaScripting::NPL::load	(	const object &	filePath,
		bool	bReload
	)			[static]

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 dll.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. For source file: when loading an NPL file, we will first find if there is an up to date compiled version in the bin directory. if there is, we will load the compiled version, otherwise we will use the text version. use bin version, if source version does not exist; use bin version, if source and bin versions are both on disk (instead of zip) and that bin version is newer than the source version. e.g. we can compile source to bin directory with file extension ".o", e.g. "script/abc.lua" can be compiled to "bin/script/abc.o", The latter will be used if available and up-to-date.

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.

Remarks:

: if one should be very careful when calling with bReload set to true, since this may lead to recursive reloading of the same file. If this occurs, it will generate C Stack overflow error message.

Returns:

: return the GliaFile reference.

static void ParaScripting::NPL::load_	(	const char *	filePath,
		bool	bReload
	)			[static]

for NPL managed only.

static void ParaScripting::NPL::EnableNetwork	(	bool	bEnable,
		const char *	CenterName,
		const char *	password
	)			[static]

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 void ParaScripting::NPL::AddDNSRecord	(	const char *	sDNSName,
		const char *	sAddress
	)			[static]

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"

static bool ParaScripting::NPL::SetTimer	(	int	nIDEvent,
		float	fElapse,
		const char *	sNeuronFile
	)			[static]

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.

static bool ParaScripting::NPL::KillTimer

(

int

nIDEvent

)

[static]

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

static bool ParaScripting::NPL::ChangeTimer	(	int	nIDEvent,
		int	dueTime,
		int	period
	)			[static]

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

static void ParaScripting::NPL::DoString

(

const object &

sCode

)

[static]

execute a given string immediately in protected mode.

Parameters:

sCode

: the code to run. the code can not be longer than some internally defined value.

Remarks:

:caution: there may be a security issue.

static string ParaScripting::NPL::SerializeToSCode	(	const char *	sStorageVar,
		const object &	input
	)			[static]

serialize a luabind object into sCode.

The object could be a value, string or a table of the above type. input also accepts ParaFileObject typed data. ParaFileObject will be converted to base64 string internally.There are size limit though of 10MB.

Parameters:

	sStorageVar	if this is "", the scode contains only the object. otherwise an assignment is made, by prefixing the scode with "[sStorageVar = ".
	input	input luabind object

Returns:

sCode the output scode

static bool ParaScripting::NPL::IsSCodePureData

(

const char *

sCode

)

[static]

verify the script code.

it returns true if the script code contains pure msg data or table. this function is used to verify scode received from the network. So that the execution of a pure data in the local runtime is harmless.

static const char* ParaScripting::NPL::GetSourceName

(

)

[static]

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.

static void ParaScripting::NPL::SetSourceName

(

const char *

sName

)

[static]

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.

static void ParaScripting::NPL::SetDefaultChannel

(

int

channel_ID

)

[static]

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

static int ParaScripting::NPL::GetDefaultChannel

(

)

[static]

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

static void ParaScripting::NPL::SetChannelProperty	(	int	channel_ID,
		int	priority,
		int	reliability
	)			[static]

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

static void ParaScripting::NPL::ResetChannelProperties

(

)

[static]

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

static void ParaScripting::NPL::GetChannelProperty	(	int	channel_ID,
		int *	priority,
		int *	reliability
	)			[static]

see also NPL_SetChannelProperty

Parameters:

	channel_ID
	priority	[out]
	reliability	[out]

static void ParaScripting::NPL::RegisterWSCallBack	(	const char *	sWebServiceFile,
		const char *	sCode
	)			[static]

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. If msg == nil, it always means that there is an error during processing, such as HTTP 404 not found. the error code either string or number will be returned in a global variable called msgerror. For example: function callbackFunc1() if(msg~=nil) then log(msg.username); -- error code in msgerror else log(tostring(msgerror)); -- error code in msgerror 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.

static void ParaScripting::NPL::UnregisterWSCallBack

(

const char *

sWebServiceFile

)

[static]

unregister web service call back for a given file.

Parameters:

sWebServiceFile

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

static void ParaScripting::NPL::AsyncDownload	(	const char *	url,
		const char *	destFolder,
		const char *	callbackScript,
		const char *	DownloaderName
	)			[static]

Asynchronously download a file or an HTTP web page from the url.

Parameters:

	destFolder:folder	path or file path. if the destFolder contains a file extension, we will save the downloaded file as the destFolder otherwise, we will save the file as the combination of the destFolder and the filename returned from the remote target.
	callbackScript,:	script code to be called, a global variable called msg is assigned, as below if url is a file: msg = {DownloadState=""|"complete"|"terminated", totalFileSize=number, currentFileSize=number, PercentDone=number} if url is a web page: msg = {DownloadState=""|"complete"|"terminated", ContentType=string that contains "text/html", Headers=string of {name:value }, StatusCode=int, StatusDescription=string, ResponseUri=string of actual url that is responding. totalFileSize=number, currentFileSize=number, PercentDone=number}

static void ParaScripting::NPL::CancelDownload

(

const char *

DownloaderName

)

[static]

cancel all asynchronous downloads that matches a certain downloader name pattern

Parameters:

DownloaderName:regular

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

static int ParaScripting::NPL::Download	(	const char *	url,
		const char *	destFolder,
		const char *	callbackScript,
		const char *	DownloaderName
	)			[static]

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

static bool ParaScripting::NPL::CreateNeuronFile

(

const char *

filePath

)

[static]

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.

static bool ParaScripting::NPL::DeleteNeuronFile

(

const char *

filePath

)

[static]

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

It will cause the GetNeuronFile function to return false.

static void ParaScripting::NPL::DoNeuronSCode	(	const char *	filePath,
		const char *	sCall
	)			[static]

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

Parameters:

	pFile,:	the file to execute
	sCall,:	the string to executed.

static void ParaScripting::NPL::DoFile	(	const char *	sNeuronFile,
		const char *	sFilename
	)			[static]

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.

static int ParaScripting::NPL::ActivateNeuronFile	(	const char *	sNeuronFile,
		const char *	code
	)			[static]

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.

static void ParaScripting::NPL::Compile

(

const char *

arguments

)

[static]

compile source The main advantages of precompiling chunks are: faster loading, protecting source code from accidental user changes, and off-line syntax checking.

Precompiling does not imply faster execution because in npl chunks are always compiled into bytecodes before being executed. compiling simply allows those bytecodes to be saved in a file for later execution. compiling can produce a single output file containing the bytecodes for all source files given. By default, the output file is named luac.out, but you can change this with the -o option. e.g. NPL.Compile("-p -o bin/script/config.o script/config.lua");

Parameters:

arguments,:

"%s [options] [filenames]" "Available options are:\n" " - process stdin\n" " -l list\n" " -o name output to file " LUA_QL("name") " (default is \"s\")\n" " -p parse only\n" " -s strip debug information\n" " -v show version information\n" " -- stop handling options\n",

---