Phidget Dictionary: Difference between revisions

From Phidgets Support
No edit summary
No edit summary
 
(19 intermediate revisions by 3 users not shown)
Line 2: Line 2:
==General Overview==
==General Overview==


The Phidget Dictionary is a central key-pair database for networked programs. It is a service provided by the [[Phidget Network Service]].  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 devices.  And 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 Network Service, which includes the Phidget Dictionary.
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.


This works because the Network Service ''already'' maintains a centralized dictionary of key-value pairs - this is what runs the Network Service itself.  We 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 starts.  When 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 example.  You may have already seen this image of how the Network Service works using the Phidget SBC from the [[Phidget Network Service]] page:
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.


[[Image:Network_service_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 Network Service 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 network service flow.png|500px|link=|alt=]]
==Using The Dictionary==
 
The 'Internal' Dictionary is really just the internal workings of the Phidget Network Service 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.
 
The 'User' Dictionary is what you can build with a Phidget Dictionary object in your code.  It is whatever collection of key-value pairs you might need for your network-distributed program, even if for just one computer.
 
At this point, you may be wondering: Why go to all the trouble of using the Dictionary?  Why not just save state within your client program?  Well, the Phidget Dictionary offers two advantages:
* It takes care of all database management for you - all you have to do is write pairs and listen for pair changes via events
* You don't have to write any code, it is already included in the Network Service!
Although both the Phidget Dictionary and the Network Service 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.


The benefits above become even more useful when you have more than one client computer.  This is one of the powerful aspects of the Phidget Network Service; 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:
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.  
[[Image:App guide dictionary network service multi.png|500px|link=|alt=]]
 
 
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 than every client talking directly to the Phidgets themselves.
 
==Using The Dictionary==
[[Image:dictionary-running.jpg|link=|right]]
To use the Dictionary, you would create a Dictionary object within your code, just like you would any other Phidget software object. To "listen" to changes of the value associated with a key, the Dictionary has a {{Code|onFilter()}} (or similar) event function. The dictionary filters using extended [https://en.wikipedia.org/wiki/Regular_expression regular expressions] for key matching to execute code for specific keys. Go into the Phidget control panel and click on the '''Network Service'' tab and ensure the service is started and the dictionary server is enabled. Here's an example of how you might use the dictionary in a C program:
<br clear="all">


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


<div class="source">
<div class="source">
<syntaxhighlight lang=c>
<syntaxhighlight lang=c>


// Declare the dictionary handle
PhidgetDictionaryHandle dict;
PhidgetDictionaryHandle dict;
char val[32];


// Create the new dictionary object using the handle
PhidgetDictionary_create(&dict);
PhidgetDictionary_create(&dict);


// Open connection to the dictionary using the object, server, port, and password
// Open connection to the dictionary using the serial number
PhidgetDictionary_openRemote(dict,"localhost",5662,NULL);
Phidget_setDeviceSerialNumber(dict, 5000);
Phidget_open(dict);


// Add a key-value pair to the dictionary
PhidgetDictionary_add(dict, "my_key", "my_value"); // add a key that does not already exist
char *key1 = "001";
PhidgetDictionary_get(dict, "my_key", val, sizeof (val)); // get the value back
char *val1 = "first";
printf("Value: %s\n",newValue);
PhidgetDictionary_add(dict,key1,val1,0); // The last parameter is 0 if you want the pairs to clear when the object is closed, and 1 if you want them to persist


// Access and print a value from the dictionary based on a given key
PhidgetDictionary_remove(dict, "my_key"); // remove the key
char newValue[20];
PhidgetDictionary_get(dict, key1, &newValue,20); // '20' refers to the length of the buffer used to store the result
printf("Value: %s",newValue);


// Remove a pair from the dictionary based on a given key
Phidget_close(dict);
PhidgetDictionary_remove(dict, key1);
 
// Close and clean up the dictionary object
PhidgetDictionary_close(dict);
PhidgetDictionary_delete(&dict);
PhidgetDictionary_delete(&dict);


Line 70: Line 46:
</div>
</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.


Have a look at the [{{SERVER}}/?view=api API documentation] for the dictionary to learn how to use these methods in the language of your choice. Select your preferred language from the first drop-down box, and select '''Dictionary API''' from the second box.
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.


Interestingly, you don't even need a Phidget to use the Dictionary!  You can use our libraries and the [[Phidget Network Service]] without any Phidgets.  Usually, there's not much to broadcast on the Network Service without a Phidget, but the Dictionary is the exception.  With it, you'll have access to centralized key-value pair database management, pre-written, that can work across many computers on a local network.
There is no way to directly list all of the keys in a dictionary.  The {{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.

Retrieved from "https://www.phidgets.com/docs/index.php?title=Phidget_Dictionary&oldid=30934"