Phidget Dictionary

Typedefs
typedef struct _CPhidgetDictionary *	CPhidgetDictionaryHandle
typedef struct _CPhidgetDictionaryListener *	CPhidgetDictionaryListenerHandle
typedef int(*	CPhidgetDictionary_OnKeyChange_Function )(CPhidgetDictionaryHandle dict, void *userPtr, const char *key, const char *value, CPhidgetDictionary_keyChangeReason reason)
Enumerations
enum	CPhidgetDictionary_keyChangeReason { PHIDGET_DICTIONARY_VALUE_CHANGED = 1, PHIDGET_DICTIONARY_ENTRY_ADDED, PHIDGET_DICTIONARY_ENTRY_REMOVING, PHIDGET_DICTIONARY_CURRENT_VALUE }
Functions
int	CPhidgetDictionary_create (CPhidgetDictionaryHandle *dict)
int	CPhidgetDictionary_close (CPhidgetDictionaryHandle dict)
int	CPhidgetDictionary_delete (CPhidgetDictionaryHandle dict)
int	CPhidgetDictionary_set_OnError_Handler (CPhidgetDictionaryHandle dict, int(*fptr)(CPhidgetDictionaryHandle, void *userPtr, int errorCode, const char *errorString), void *userPtr)
int	CPhidgetDictionary_addKey (CPhidgetDictionaryHandle dict, const char *key, const char *value, int persistent)
int	CPhidgetDictionary_removeKey (CPhidgetDictionaryHandle dict, const char *pattern)
int	CPhidgetDictionary_set_OnKeyChange_Handler (CPhidgetDictionaryHandle dict, CPhidgetDictionaryListenerHandle *dictlistener, const char *pattern, CPhidgetDictionary_OnKeyChange_Function fptr, void *userPtr)
int	CPhidgetDictionary_remove_OnKeyChange_Handler (CPhidgetDictionaryListenerHandle dictlistener)
int	CPhidgetDictionary_getKey (CPhidgetDictionaryHandle dict, const char *key, char *value, int valuelen)
int	CPhidgetDictionary_set_OnServerConnect_Handler (CPhidgetDictionaryHandle dict, int(*fptr)(CPhidgetDictionaryHandle dict, void *userPtr), void *userPtr)
int	CPhidgetDictionary_set_OnServerDisconnect_Handler (CPhidgetDictionaryHandle dict, int(*fptr)(CPhidgetDictionaryHandle dict, void *userPtr), void *userPtr)
int	CPhidgetDictionary_getServerID (CPhidgetDictionaryHandle dict, const char **serverID)
int	CPhidgetDictionary_getServerAddress (CPhidgetDictionaryHandle dict, const char **address, int *port)
int	CPhidgetDictionary_getServerStatus (CPhidgetDictionaryHandle dict, int *serverStatus)
int	CPhidgetDictionary_openRemote (CPhidgetDictionaryHandle dict, const char *serverID, const char *password)
int	CPhidgetDictionary_openRemoteIP (CPhidgetDictionaryHandle dict, const char *address, int port, const char *password)

---

Detailed Description

These calls are specific to the Phidget Dictionary.

---

Typedef Documentation

typedef struct _CPhidgetDictionary* CPhidgetDictionaryHandle

A Phidget Dictionary handle. A Phidget Dictionary handle

typedef struct _CPhidgetDictionaryListener* CPhidgetDictionaryListenerHandle

A Dictionary key listener handle. A Phidget DictionaryListener handle

typedef int( * CPhidgetDictionary_OnKeyChange_Function)(CPhidgetDictionaryHandle dict, void *userPtr, const char *key, const char *value, CPhidgetDictionary_keyChangeReason reason)

Callback function for KeyChange events.

Parameters:

	dict	Dictionary from which this event originated.
	userPtr	User defined data.
	key	Key value.
	value	Value value.
	reason	Reason for KeyChange event.

---

Enumeration Type Documentation

enum CPhidgetDictionary_keyChangeReason

Possible reasons for a key event.

Enumerator:

PHIDGET_DICTIONARY_VALUE_CHANGED	The value of an existing key/value pair changed.
PHIDGET_DICTIONARY_ENTRY_ADDED	A new key/value pair was added.
PHIDGET_DICTIONARY_ENTRY_REMOVING	A key is being removed.
PHIDGET_DICTIONARY_CURRENT_VALUE	Initial state received once a handler was added.

---

Function Documentation

int CPhidgetDictionary_create

(

CPhidgetDictionaryHandle *

dict

)

Creates a Phidget Dictionary handle.

Parameters:

dict

A pointer to an unallocated phidget dictionary handle.

int CPhidgetDictionary_close

(

CPhidgetDictionaryHandle

dict

)

Closes the connection to a Phidget Dictionary.

Parameters:

dict

An opened phidget dictionary handle.

int CPhidgetDictionary_delete

(

CPhidgetDictionaryHandle

dict

)

Frees a Phidget Dictionary handle.

Parameters:

dict

A closed dictionary handle.

int CPhidgetDictionary_set_OnError_Handler	(	CPhidgetDictionaryHandle	dict,
		int(*)(CPhidgetDictionaryHandle, void *userPtr, int errorCode, const char *errorString)	fptr,
		void *	userPtr
	)

Sets the error handler callback function. This is called when an asynchronous error occurs.

Parameters:

	dict	A phidget dictionary handle.
	fptr	Callback function pointer.
	userPtr	A pointer for use by the user - this value is passed back into the callback function.

int CPhidgetDictionary_addKey	(	CPhidgetDictionaryHandle	dict,
		const char *	key,
		const char *	value,
		int	persistent
	)

Adds a key/value pair to the dictionary. Or, changes an existing key's value.

Parameters:

	dict	A connected dictionary handle.
	key	The key value.
	value	The value value.
	persistent	Whether the key stays in the dictionary after disconnection.

int CPhidgetDictionary_removeKey	(	CPhidgetDictionaryHandle	dict,
		const char *	pattern
	)

Removes a set of keys from the dictionary.

Parameters:

	dict	A connected dictionary handle.
	pattern	A regular expression representing th eset of keys to remove.

int CPhidgetDictionary_set_OnKeyChange_Handler	(	CPhidgetDictionaryHandle	dict,
		CPhidgetDictionaryListenerHandle *	dictlistener,
		const char *	pattern,
		CPhidgetDictionary_OnKeyChange_Function	fptr,
		void *	userPtr
	)

Adds a key listener to an opened dictionary. Note that this should only be called after the connection to the dictionary has been made - unlike all other events.

Parameters:

	dict	A connected dictionary handle.
	dictlistener	A pointer to an unallocated dictionary key listener handle.
	pattern	A regular expression representing the set of keys to monitor.
	fptr	Callback function pointer.
	userPtr	A pointer for use by the user - this value is passed back into the callback function.

int CPhidgetDictionary_remove_OnKeyChange_Handler

(

CPhidgetDictionaryListenerHandle

dictlistener

)

Removes a key listener.

Parameters:

dictlistener

The dictionary key listener created by CPhidgetDictionary_set_OnKeyChange_Handler

int CPhidgetDictionary_getKey	(	CPhidgetDictionaryHandle	dict,
		const char *	key,
		char *	value,
		int	valuelen
	)

Gets a key value. If more then one key matches, only the first value is returned.

Parameters:

	dict	A phidget dictionary handle.
	key	A key value to look up.
	value	A user array for the value to be stored in. Set to NULL if the key does not exist.
	valuelen	Length of the value array.

int CPhidgetDictionary_set_OnServerConnect_Handler	(	CPhidgetDictionaryHandle	dict,
		int(*)(CPhidgetDictionaryHandle dict, void *userPtr)	fptr,
		void *	userPtr
	)

Sets a server connect handler callback function. This is called when a connection to the sever has been made.

Parameters:

	dict	A phidget dictionary handle.
	fptr	Callback function pointer.
	userPtr	A pointer for use by the user - this value is passed back into the callback function.

int CPhidgetDictionary_set_OnServerDisconnect_Handler	(	CPhidgetDictionaryHandle	dict,
		int(*)(CPhidgetDictionaryHandle dict, void *userPtr)	fptr,
		void *	userPtr
	)

Sets a server disconnect handler callback function. This is called when a connection to the server has been lost.

Parameters:

	dict	A phidget dictionary handle.
	fptr	Callback function pointer.
	userPtr	A pointer for use by the user - this value is passed back into the callback function.

int CPhidgetDictionary_getServerID	(	CPhidgetDictionaryHandle	dict,
		const char **	serverID
	)

Gets the server ID.

Parameters:

	dict	A connected dictionary handle.
	serverID	A pointer which will be set to a char array containing the server ID string.

int CPhidgetDictionary_getServerAddress	(	CPhidgetDictionaryHandle	dict,
		const char **	address,
		int *	port
	)

Gets the address and port.

Parameters:

	dict	A connected dictionary handle.
	address	A pointer which will be set to a char array containing the address string.
	port	An int pointer for returning the port number.

int CPhidgetDictionary_getServerStatus	(	CPhidgetDictionaryHandle	dict,
		int *	serverStatus
	)

Gets the connected to server status.

Parameters:

	dict	An opened dictionary handle.
	serverStatus	An int pointer for returning the server status. Possible codes are PHIDGET_ATTACHED and PHIDGET_NOTATTACHED.

int CPhidgetDictionary_openRemote	(	CPhidgetDictionaryHandle	dict,
		const char *	serverID,
		const char *	password
	)

Opens a Phidget dictionary by ServerID. Note that this requires Bonjour (mDNS) to be running on both the host and the server.

Parameters:

	dict	A phidget dictionary handle.
	serverID	Server ID. Specify NULL to open any.
	password	Password. Can be NULL if the server is running unsecured.

int CPhidgetDictionary_openRemoteIP	(	CPhidgetDictionaryHandle	dict,
		const char *	address,
		int	port,
		const char *	password
	)

Opens a Phidget dictionary by address and port.

Parameters:

	dict	A phidget dictionary handle.
	address	Address. This can be a hostname or IP address.
	port	Port number. Default is 5001.
	password	Password. Can be NULL if the server is running unsecured.