Phidget Dictionary: Difference between revisions

From Phidgets Support
(Created page with "==General Overview== The Phidget Dictionary is a service provided by the Phidget WebService. It allows you to store program data centrally - in the form of key-value pai...")
 
No edit summary
 
(26 intermediate revisions by 4 users not shown)
Line 1: Line 1:
[[Category:Overview]]
==General Overview==
==General Overview==


The Phidget Dictionary is a service provided by the [[Phidget WebService]].  It allows you to store program data centrally - in the form of key-value pairs - on the same server as your Phidgets.
[[Image:Dictionary-networkserver.jpg|600px|link=|alt=]]


A Dictionary is like any other Phidget software object: You create and open it (though you don't have to wait for attachment or attach it in any way)You can subscribe to data change events, and get updates on these events from multiple devicesAnd when you're done, you simply close and delete it.  Just like any other Phidget software object over the network, you run the functional code on your client, and the server simply runs the Phidget WebService, which includes the Phidget Dictionary.
The Dictionary is a Phidget channel class that exports a key-value pair databaseDictionaries are created and made accessible by the [[Phidget Network Server]]A Dictionary channel is created and opened like any other Phidget channel.  Matching is done using either the serial number or the label assigned to the dictionary.


This works because the WebService ''already'' maintains a centralized dictionary of key-value pairs - this is what runs the WebService itselfWe expose this data storage to you, the user, so that it can be customized and can be accessed and changed from any number of clients.
The backing pseudo-device that exports the Dictionary device channel is maintained by the [[Phidget Network Server]], and is created when the server startsWhen the server exits, the pseudo-device is deleted, and any changes made to a dictionary are lost.


Since the Dictionary is a popular feature on our Phidget Single Board Computer (SBC), we will use that as an exampleYou may have already seen this image of how the WebService works using the Phidget SBC from the [[Phidget WebService]] page:
The basic functionality of a Dictionary is to maintain configuration information in a central locationMultiple clients can attach to the same dictionary, and set handlers for ''add'', ''update'' and ''delete'' events, making the dictionary useful for monitoring and communicating state.


[[Image:webservice_general_sbctopc.png|500px|link=|alt=]]
==Creating a Dictionary==
Dictionaries are managed by the [[Phidget Network Server]]. To create a dictionary, go to the [[Phidget Control Panel]] and click on the '''Network Server''' tab.  There are options to create and manage dictionaries.  The server must be enabled for clients to access dictionaries.


Now that we know about the Phidget Dictionary, if we were to expand the WebService out into its components, it would look like this:
On Linux, refer to the README for information on how to enable the dictionary feature in the [[Phidget Network Server]], and for the syntax of dictionary configuration files.


[[Image:App guide dictionary webservice flow.png|500px|link=|alt=]]
==Using The Dictionary==
 
To access a dictionary, create a channel, set the serial number or the label, and open the channel.
To "listen" for changes to the Dictionary,  {{Code|onAdd()}}, {{Code|onRemove()}}, and {{Code|onUpdate()}} event handlers can be set.  Refer to the {{Phidget22API}} to see the methods supported by Dictionary.
 
Here's an example of how you might use the dictionary in a C program:


The 'Internal' Dictionary is really just the internal workings of the Phidget Webservice itself.  This shares the key-value pair database with the user Dictionary.  In fact, when using a dictionary object, if you catch all key events you will see ones that are produced by Phidgets!  You should never modify these keys - i.e. ones that start with /PSK/ or /PCK/ - unless you want to explicitly modify Phidget-specific data. This is highly discouraged, as it’s very easy to break things; however, listening to these keys is fine if so desired.
<div class="source">
<syntaxhighlight lang=c>


The 'User' Dictionary is the typical functionality of the Phidget Dictionary object that you can create and use in your code.  Although both the Phidget Dictionary and the Webservice use the same data repository (because they are, as described in the previous paragraph, actually the same thing), you usually won't be concerned with Phidget data and will instead be creating and storing your own data to run your program with state.
PhidgetDictionaryHandle dict;
char val[32];


With the two-computer example above, you may be wondering: Why go to all the trouble of using the Dictionary?  Why not just save state within your client program?
PhidgetDictionary_create(&dict);


The answer becomes obvious when you have more than one client computer.  This is one of the powerful aspects of the Phidget Webservice; that is, more than one computer can control Phidgets by making your system networked.  In this case, having a centralized store of data that all clients can 'subscribe' to in order to act when it changes is a very powerful tool:
// Open connection to the dictionary using the serial number
Phidget_setDeviceSerialNumber(dict, 5000);
Phidget_open(dict);


[[Image:App guide dictionary webservice multi.png|500px|link=|alt=]]
PhidgetDictionary_add(dict, "my_key", "my_value"); // add a key that does not already exist
PhidgetDictionary_get(dict, "my_key", val, sizeof (val)); // get the value back
printf("Value: %s\n",newValue);


PhidgetDictionary_remove(dict, "my_key"); // remove the key


The intended use for the dictionary is as a central repository for communication and persistent storage of data between several client applications. For example, it can be used as a higher level interface exposed by one application that controls the Phidgets for others to access, rather then every client talking directly to the Phidgets themselves.
Phidget_close(dict);
PhidgetDictionary_delete(&dict);


==Using The Dictionary==
</syntaxhighlight>
</div>
 
==Notes==
 
A common mistake is to assume an event will be delivered to the channel that triggered the event.  This is not the case.  For example, when a channel adds a key, that channel's add event handler is not called.
 
It is an error to {{Code|Add()}} a key that already exists in the dictionary.  {{Code|Set()}} should be used to update existing keys, creating the key if it does not already exist.


To use the Dictionary, you would create a Dictionary object within your code, just like you would any other Phidget software object.  We describe - in a general manner - how to create software objects on the [[General Phidget Programming]] page, and even more information can be found specific to your language on the [[Software Overview#Language Support|page for your language]]To "listen" to changes of the value associated with a key, the Dictionary has a {{Code|KeyValueChanged()}} (or similar) event function. The dictionary makes use of extended regular expressions for key matching to execute code for specific keys.
There is no way to directly list all of the keys in a dictionaryThe {{Code|Scan()}} method allows code to access the existing keys, but only returns the number of keys that can be held in a limited sized buffer. This interface was chosen as the dictionary could contain more keys than could reasonably be returned in a single network request.

Latest revision as of 17:53, 6 March 2019

General Overview

The Dictionary is a Phidget channel class that exports a key-value pair database. Dictionaries are created and made accessible by the Phidget Network Server. A Dictionary channel is created and opened like any other Phidget channel. Matching is done using either the serial number or the label assigned to the dictionary.

The backing pseudo-device that exports the Dictionary device channel is maintained by the Phidget Network Server, and is created when the server starts. When the server exits, the pseudo-device is deleted, and any changes made to a dictionary are lost.

The basic functionality of a Dictionary is to maintain configuration information in a central location. Multiple clients can attach to the same dictionary, and set handlers for add, update and delete events, making the dictionary useful for monitoring and communicating state.

Creating a Dictionary

Dictionaries are managed by the Phidget Network Server. To create a dictionary, go to the Phidget Control Panel and click on the Network Server tab. There are options to create and manage dictionaries. The server must be enabled for clients to access dictionaries.

On Linux, refer to the README for information on how to enable the dictionary feature in the Phidget Network Server, and for the syntax of dictionary configuration files.

Using The Dictionary

To access a dictionary, create a channel, set the serial number or the label, and open the channel. To "listen" for changes to the Dictionary, onAdd(), onRemove(), and onUpdate() event handlers can be set. Refer to the Phidget22 API to see the methods supported by Dictionary.

Here's an example of how you might use the dictionary in a C program:

PhidgetDictionaryHandle dict;
char val[32];

PhidgetDictionary_create(&dict);

// Open connection to the dictionary using the serial number
Phidget_setDeviceSerialNumber(dict, 5000);
Phidget_open(dict);

PhidgetDictionary_add(dict, "my_key", "my_value"); // add a key that does not already exist 
PhidgetDictionary_get(dict, "my_key", val, sizeof (val)); // get the value back
printf("Value: %s\n",newValue);

PhidgetDictionary_remove(dict, "my_key"); // remove the key

Phidget_close(dict);
PhidgetDictionary_delete(&dict);

Notes

A common mistake is to assume an event will be delivered to the channel that triggered the event. This is not the case. For example, when a channel adds a key, that channel's add event handler is not called.

It is an error to Add() a key that already exists in the dictionary. Set() should be used to update existing keys, creating the key if it does not already exist.

There is no way to directly list all of the keys in a dictionary. The Scan() method allows code to access the existing keys, but only returns the number of keys that can be held in a limited sized buffer. This interface was chosen as the dictionary could contain more keys than could reasonably be returned in a single network request.