NDChannel Class Reference

NetDog Communications Channel. More...

List of all members.

Public Member Functions
	NDChannel (void *)
	Constructor, do not call this directly; use NDCore::createChannel instead.
	~NDChannel ()
	Destructor, call this to shut down an entire channel.
NDChannelID	getChannelID (void)
	Returns the channelID associated with this channel.
NDResult	loginToHost (NDCore::SocketType stype, NDSocketAddress *sa, const char *username, const char *password, NDConn **c=NULL, const char *remote_key_file=NULL)
	Create an authenticated connection to a remote host via UDP or TCP.
NDResult	becomeLoginAcceptor (NDLoginCallback *cback)
	Allow channel to accept new connections.
NDResult	registerEventType (NDEvent::Type evt_type, const char *evt_name, NDEventCallback *callback)
	Registers a new event type.
NDEvent *	createEvent (NDEvent::Type evt_type, uint32_t evt_size)
	Creates a new event object.
NDIdentity	getLocalIdentity (void)
	Returns the local node's identity record.
NDResult	setLocalIdentity (const NDIdentity &id)
	Sets the local node's identity record.
NDResult	generateLocalKeys (uint32_t bits)
	Generates public-private keypairs for use in encryption.
NDResult	saveLocalKeys (const char *pub_file_name, const char *priv_file_name)
	Saves previously generated public-private keypairs into files.
NDResult	loadLocalKeys (const char *pub_file_name, const char *priv_file_name)
	Loads public-private keypair from files into this channel.
NDResult	registerRpcHandler (int32_t proc_id, NDRpcHandler *srv)
	Registers a RPC handler.
NDRpcRequest *	createRpcRequest (NDNodeID srv_node, int32_t proc_id, uint32_t req_size)
	Creates a new RPC request object.
NDTimeValue	getUniverseTime (void)
	Gets miliseconds since the start of the virtual universe.
NDResult	setUniverseTime (NDTimeValue t)
	Sets miliseconds since the start of the virtual universe.
NDResult	registerObjectHandler (NDObjectHandler *ohan)
	Registers object callback handler.
NDResult	becomeObjectAuthority (NDObjectAuthority *oauth)
	Promotes this channel to an object authority and registers object authority handler.
NDResult	setObjectUpdatePeriod (NDTimeValue period)
	Sets automated object update period.
NDResult	sendObjectUpdates (void)
	Sends object updates.
NDObject *	createObject (NDObjectType otype)
	Creates a new local object.
NDObject *	getUserObject (void)
	Gets the object associated with our user, e.g. the object for our own player, etc.
NDObject *	getObjectByID (NDObjectID objid, bool request_from_server=false)
	Looks up an object by its objectID, fetching the object from the server if necessary (and desired).
NDResult	flushObject (NDObject *obj)
	Immediately propogates all local modifications to this object over the network.
NDResult	deleteObject (NDObject *obj)
	Deletes the specified object.
NDResult	getObjectIDList (NDObjectID **obj_list, uint32_t *num_objs)
	Gets a list of IDs of all objects in this channel.
Public Attributes
void *	_ndchannel

---

Detailed Description

A single NDChannel represents a link to a single NetDog network, and consists of one or more NDConn connections. (Technically, there may not be any connections, e.g. for a server just after startup.)

---

Constructor & Destructor Documentation

NDChannel::NDChannel

(

void *

ptr

)

Constructor, do not call this directly; use NDCore::createChannel instead

NDChannel::~NDChannel

(

)

Destructor, call this to shut down an entire channel

---

Member Function Documentation

NDResult NDChannel::becomeLoginAcceptor

(

NDLoginCallback *

cback

)

This allows the node to accept new connection that require authentication.

Parameters:

cback

This is a pointer to a NDLoginCallback object. This objects handleLoginCallback() will be called to handle authentication for incomming connections.

Returns:

NDRES_OK on success

NDResult NDChannel::becomeObjectAuthority

(

NDObjectAuthority *

oauth

)

Parameters:

*oauth

NDObjectAuthority callback object

NDEvent * NDChannel::createEvent	(	NDEvent::Type	evt_type,
		uint32_t	evt_size
	)

Creates a new NDEvent object, which can be used to issue a new event. This is the only way to create a new NDEvent object.

Parameters:

	evt_type
	evt_size

Returns:

Pointer to an NDEvent object. NULL on error.

NDObject * NDChannel::createObject

(

NDObjectType

otype

)

Creates a new local object. The object is "empty" until attributes (fields) have been written into it. The object is local (visible only to this client (or server)) until publish() has been called on it.

Parameters:

otype

the object type for this object

Returns:

pointer to the newly created object

NDRpcRequest * NDChannel::createRpcRequest	(	NDNodeID	srv_node,
		int32_t	proc_id,
		uint32_t	req_size
	)

When performing an RPC request, you must...

Parameters:

	srv_node
	proc_id
	req_size

Returns:

New RPC request object, NULL on error

NDResult NDChannel::deleteObject

(

NDObject *

obj

)

Deletes the specified object locally and from the server and all clients

Parameters:

obj

a pointer to the object to be deleted

Returns:

NDRES_OK if the operation was successful

NDRES_ACCESS_DENIED if the server's validation routine denied this deletion

NDRES_ALLOC if there was an internal memory allocation failure (e.g. out of free memory)

NDResult NDChannel::flushObject

(

NDObject *

obj

)

Immediately propogates all local modifications to this object over the network, i.e. to the server and all clients.

Parameters:

obj

a pointer to the object to be flushed

Returns:

NDRES_OK if the operation was successful

NDRES_CANT_AUTH_FLUSH if this method is called by the object authority (e.g. the server) since the object authority is not allowed to flush objects

NDResult NDChannel::generateLocalKeys

(

uint32_t

bits

)

Generates public-private keypairs for use in encryption

Parameters:

bits

random data used to seed the generation of keys

Returns:

NDRES_OK if key generation succeeded

value other than NDRES_OK on failure

NDChannelID NDChannel::getChannelID

(

void

)

Returns the channelID associated with this channel

NDIdentity NDChannel::getLocalIdentity

(

void

)

Returns the local identity record. This contains information about the identity, roles, authorization of the local node.

Returns:

Reference to NDIdentity.

NDObject * NDChannel::getObjectByID	(	NDObjectID	objid,
		bool	request_from_server = false
	)

Looks up an object by its objectID, fetching the object from the server if necessary (and desired)

Parameters:

	objid	the objectID of the object to look up
	request_from_server	specifies whether the object should be retrieved from the server if it is not present locally

Returns:

pointer to the object with the specified objectID, or NULL if no such object exists (or it doesn't exist locally and request_from_server was set to false)

NDResult NDChannel::getObjectIDList	(	NDObjectID **	obj_list,
		uint32_t *	num_objs
	)

Gets a list of IDs of all objects in this channel

Parameters:

	obj_list	pointer to an array of object IDs into which the list should be written
	num_objs	pointer into which to write the size of the list (i.e. the total number of objects)

Returns:

NDRES_OK if the operation was successful

NDRES_NULL_POINTER if the obj_list argument was NULL

NDTimeValue NDChannel::getUniverseTime

(

void

)

Returns:

time in miliseconds

NDObject * NDChannel::getUserObject

(

void

)

Gets the object associated with our user, e.g. the object for our own player, etc.

Returns:

pointer to our user's object

NDResult NDChannel::loadLocalKeys	(	const char *	pub_file_name,
		const char *	priv_file_name
	)

Loads public-private keypair from files into this channel

Parameters:

	pub_file_name	file name from which to load the public key
	priv_file_name	file name from which to load the private key

Returns:

NDRES_OK if the files were successfully loaded

NDRES_FILE_ERROR if there was a problem reading the specified files

NDRES_CRYPTO_INVALID_KEY if the keys in the specified were invalid

NDResult NDChannel::loginToHost	(	NDCore::SocketType	stype,
		NDSocketAddress *	sa,
		const char *	username,
		const char *	password,
		NDConn **	c = NULL,
		const char *	remote_key_file = NULL
	)

This node assumes a client role, and connects/authenticates with the remote host, Authentication, and authorization trust of the remote host is assumed. Remote host can be authenticated using it public key.

Parameters:

	stype	Connect via UDP or TCP. Acceptable values are NDCore::UDP or NDCore::TCP
	sa	Address of remote host
	username	Plain text username for authentication
	password	Plain text password for authentication
	c	Pointer into which the newly created conn pointer will be stored (NULL may be passed if the conn pointer is not needed)
	remote_key_file	File containing remote hosts public key, NULL if no encryption is required

Returns:

NDRES_OK on success

NDResult NDChannel::registerEventType	(	NDEvent::Type	evt_type,
		const char *	evt_name,
		NDEventCallback *	callback
	)

Registers a new event type. An event type ID, event name and event handler callback object are required.

Parameters:

	evt_type
	evt_name
	callback

Returns:

NDRES_OK on success

NDResult NDChannel::registerObjectHandler

(

NDObjectHandler *

ohan

)

Parameters:

*ohan

NDObjectHandler callback object

NDResult NDChannel::registerRpcHandler	(	int32_t	proc_id,
		NDRpcHandler *	srv
	)

Registers an RPC handler. It registers the procedure ID, and uses the NDRpcHandler callback object to process any RPC requests to this node.

Parameters:

	proc_id	The procedure ID
	*srv	The callback object

Returns:

NDRES_OK on success

NDResult NDChannel::saveLocalKeys	(	const char *	pub_file_name,
		const char *	priv_file_name
	)

Saves previously generated public-private keypairs into files

Parameters:

	pub_file_name	file name for the public key
	priv_file_name	file name for the private key

Returns:

NDRES_OK if the files were successfully saved

NDRES_FILE_ERROR if there was a problem writing to the specified files

NDResult NDChannel::sendObjectUpdates

(

void

)

Initiates sending of all updates object information, use if you have set the Object Update Period to zero.

NDResult NDChannel::setLocalIdentity

(

const NDIdentity &

id

)

Sets the local node's identity record.

Parameters:

id

the identity record value to be set for this channel

Returns:

Reference to NDIdentity.

NDResult NDChannel::setObjectUpdatePeriod

(

NDTimeValue

period

)

Parameters:

period

Number of miliseconds between sending object update messages. A value of zero (default) disables automated updates.

NDResult NDChannel::setUniverseTime

(

NDTimeValue

t

)

Parameters:

t

time in miliseconds