SoftBank Robotics documentation What's new in NAOqi 2.5?

ALMemory API

NAOqi Core - Overview | API | Tutorial

Namespace : AL

#include <alproxies/almemoryproxy.h>

Methods

void ALMemoryProxy::declareEvent(const std::string& eventName)

Declares an event to allow future subscriptions to the event

Parameters:
  • eventName – The name of the event
void ALMemoryProxy::declareEvent(const std::string& eventName, const std::string& extractorName)

Declares an event to allow future subscriptions to the event

Parameters:
  • eventName – The name of the event
  • extractorName – The name of the extractor capable of creating the event
AL::ALValue ALMemoryProxy::getData(const std::string& key)

Gets the value of a key-value pair stored in memory

Parameters:
  • key – Name of the value.
Returns:

The data as an AL::ALValue. This can often be cast transparently into the original type.
AL::ALValue ALMemoryProxy::getData(const std::string& key, const int& deprecatedParameter)

Deprecated since version 1.12: use the version of this method with no second parameter.

Gets the value of a key-value pair stored in memory

Parameters:
  • key – Name of the value.
  • deprecatedParameter – This parameter has no effect, but is left for compatibility reason.
Returns:

The data as an AL::ALValue
std::vector<std::string> ALMemoryProxy::getDataList(const std::string& filter)

Gets a list of all key names that contain a given string

Parameters:
  • filter – A string used as the search term
Returns:

A list of all the data key names that contain the given string.
std::vector<std::string> ALMemoryProxy::getDataListName()

Gets the key names for all the key-value pairs in memory

Returns:A list containing the keys in memory
AL::ALValue ALMemoryProxy::getDataOnChange(const std::string& key, const int& deprecatedParameter)

Blocks the caller until the value of a key changes

Deprecated since version 1.12: call ALMemoryProxy::getData on your own and compare when the data change.

Parameters:
  • key – Name of the data.
  • deprecatedParameter – this parameter has no effect
Returns:

an array containing all the retrieved data
void* ALMemoryProxy::getDataPtr(const std::string& key)

Gets a pointer to 32 a bit data item. Beware, the pointer will only be valid during the lifetime of the ALMemoryProxy object. Use with care, at initialization, not every loop.

Parameters:
  • key – Name of the data.
Returns:

A pointer converted to int
AL::ALValue ALMemoryProxy::getDescriptionList(const std::vector<std::string>& keys)

Gets a description of all given keys

Parameters:
  • keys – List of keys. (empty to get all descriptions)
Returns:

An array of (key, type, description) where type is “data” or “event”
AL::ALValue ALMemoryProxy::getEventHistory(const std::string& pName)
Parameters:
  • key – Name of the variable
Returns:

A sequence of past values of the key with their timestamps as an array of ALValues, each with 3 items: * memoryKey value, * first part of the timestamp (seconds), * second part of the timestamp (microseconds).
std::vector<std::string> ALMemoryProxy::getEventList()

Gets a list containing the names of all the declared events

Returns:A list containing the names of all events
AL::ALValue ALMemoryProxy::getTimestamp(const std::string& memoryKey)

Gets memoryKey value and its timestamps.

Parameters:
  • memoryKey – Name of the memoryKey in the ALMemory
Returns:

An ALValue with 3 items: * memoryKey value, * first part of the timestamp (seconds), * second part of the timestamp (microseconds).
std::vector<std::string> ALMemoryProxy::getExtractorEvent(const std::string& extractorName)

Gets the list of all events generated by a given extractor

Parameters:
  • extractorName – The name of the extractor
Returns:

A list containing the names of the events associated with the given extractor
AL::ALValue ALMemoryProxy::getListData(const AL::ALValue& keyList)

Gets the values associated with the given list of keys. This is more efficient than calling getData many times, especially over the network.

Parameters:
  • keyList – An array containing the key names.
Returns:

An array containing all the values corresponding to the given keys.
std::vector<std::string> ALMemoryProxy::getMicroEventList()

Gets a list containing the names of all the declared micro events

Returns:A list containing the names of all the microEvents
std::vector<std::string> ALMemoryProxy::getSubscribers(const std::string& name)

Gets a list containing the names of subscribers to an event.

Parameters:
  • name – Name of the event or micro-event
Returns:

List of subscriber names
std::string ALMemoryProxy::getType(const std::string& key)

Gets the storage class of the stored data. This is not the underlying POD type.

Parameters:
  • key – Name of the variable
Returns:

String type: Data, Event, MicroEvent
void ALMemoryProxy::insertData(const std::string& key, const int& value)

Inserts a key-value pair into memory, where value is an int

Parameters:
  • key – Name of the value to be inserted.
  • value – The int to be inserted
void ALMemoryProxy::insertData(const std::string& key, const float& value)

Inserts a key-value pair into memory, where value is a float

Parameters:
  • key – Name of the value to be inserted.
  • value – The float to be inserted
void ALMemoryProxy::insertData(const std::string& key, const std::string& value)

Inserts a key-value pair into memory, where value is a string

Parameters:
  • key – Name of the value to be inserted.
  • value – The string to be inserted
void ALMemoryProxy::insertData(const std::string& key, const AL::ALValue& data)

Inserts a key-value pair into memory, where value is an ALValue

Parameters:
  • key – Name of the value to be inserted.
  • data – The ALValue to be inserted. This could contain a basic type, or a more complex array. See the ALValue documentation for more information.
void ALMemoryProxy::insertListData(const AL::ALValue& list)

Inserts a list of key-value pairs into memory.

Parameters:
  • list – An ALValue list of the form [[Key, Value],...]. Each item will be inserted.
void ALMemoryProxy::raiseEvent(const std::string& name, const AL::ALValue& value)

Publishes the given data to all subscribers.

Parameters:
  • name – Name of the event to raise.
  • value – The data associated with the event. This could contain a basic type, or a more complex array. See the ALValue documentation for more information.
void ALMemoryProxy::raiseMicroEvent(const std::string& name, const AL::ALValue& value)

Publishes the given data to all subscribers.

Parameters:
  • name – Name of the event to raise.
  • value – The data associated with the event. This could contain a basic type, or a more complex array. See the libalvalue documentation for more information.
void ALMemoryProxy::removeData(const std::string& key)

Removes a key-value pair from memory

Parameters:
  • key – Name of the data to be removed.
void ALMemoryProxy::removeMicroEvent(const std::string& name)

Removes a micro event from memory and unsubscribes any existing subscribers.

Parameters:
  • name – Name of the event to remove.
void ALMemoryProxy::setDescription(const std::string& name, const std::string& description)

Sets the description of a memory entry.

Parameters:
  • name – The name of the key to document
  • description – The description
void ALMemoryProxy::subscribeToEvent(const std::string& name, const std::string& callbackModule, const std::string& callbackMethod)

Subscribes to an event and automatically launches the module that declared itself as the generator of the event if required.

Parameters:
  • name – The name of the event to subscribe to
  • callbackModule – Name of the module to call with notifications
  • callbackMethod – Name of the module’s method to call when a data is changed

Look at the following example for details: Creating events (DEPRECATED)

C++ callback signature:

class MyModule : public AL::ALModule {
public:
  void myCallback(const std::string &key, const AL::ALValue &value, const AL::ALValue &message);
};

Python callback signature:

# create python module
class MyModule(ALModule):
  """ Mandatory docstring.
      comment needed to create a new python module
  """

  def myCallback(self, key, value, message):
    """ Mandatory docstring.
        comment needed to create a bound method
    """
    pass
void ALMemoryProxy::subscribeToEvent(const std::string& name, const std::string& callbackModule, const std::string& callbackMessage, const std::string& callbackMethod)

Deprecated since version 1.12: use the version without the callbackMessage parameter.

Subscribes to event and automatically launches the module capable of generating the event if it is not already running. Use the version without the callbackMessage parameter.

Parameters:
  • name – The name of the event to subscribe to
  • callbackModule – Name of the module to call with notifications
  • callbackMessage – DEPRECATED Message included in the notification.
  • callbackMethod – Name of the module’s method to call when a data is changed
void ALMemoryProxy::subscribeToMicroEvent(const std::string& name, const std::string& callbackModule, const std::string& callbackMessage, const std::string& callbackMethod)

Subscribes to a microEvent. Subscribed modules are notified on their callback method whenever the data is updated, even if the new value is the same as the old value.

Parameters:
  • name – Name of the data.
  • callbackModule – Name of the module to call with notifications
  • callbackMessage – Message included in the notification. This can be used to disambiguate multiple subscriptions.
  • callbackMethod – Name of the module’s method to call when a data is changed

Look at the following example for details: Creating events (DEPRECATED)

C++ callback signature:

class MyModule : public AL::ALModule {
public:
  void myCallback(const std::string &key, const AL::ALValue &value, const AL::ALValue &message);
};

Python callback signature:

# create python module
class MyModule(ALModule):
  """ Mandatory docstring.
      comment needed to create a new python module
  """

  def myCallback(self, key, value, message):
    """ Mandatory docstring.
        comment needed to create a bound method
    """
    pass
void ALMemoryProxy::unregisterModuleReference(const std::string& moduleName)

Informs ALMemoryProxy that a module doesn’t exist anymore.

Parameters:
  • moduleName – Name of the departing module.
void ALMemoryProxy::unsubscribeToEvent(const std::string& name, const std::string& callbackModule)

Unsubscribes a module from the given event. No further notifications will be received. The module capable of generating the event is automatically stopped when the last subscriber unsubscribes.

Parameters:
  • name – The name of the event
  • callbackModule – The name of the module that was given when subscribing.
void ALMemoryProxy::unsubscribeToMicroEvent(const std::string& name, const std::string& callbackModule)

Unsubscribes from the given event. No further notifications will be received.

Parameters:
  • name – Name of the event.
  • callbackModule – The name of the module that was given when subscribing.
qi::AnyObject ALMemoryProxy::subscriber(const std::string& name)

Return a dynamic object with a signal named signal which will trigger when the event is triggered. If the event does not exist, it is created. See Subscribing to an event from ALMemory.

You must keep the object alive to keep the signal connections alive.

Parameters:
  • name – Name of the event.

Events

Event: "NAOqiReady"
callback(std::string eventName, std::string subscriberIdentifier)

Raised when all the auto-loaded modules have been loaded. See How it works to understand what is an auto-loaded module.

Event: "ALMemory/KeyAdded"
callback(std::string eventName, const std::string& keyName, std::string subscriberIdentifier)

Raised after a key is created in ALMemory, carrying the name of the freshly created key.

Event: "ALMemory/KeyRemoved"
callback(std::string eventName, const std::string& keyName, std::string subscriberIdentifier)

Raised after a key is removed from ALMemory, carrying the name of the concerned key.

Event: "ALMemory/KeyTypeChanged"
callback(std::string eventName, const std::string& keyName, std::string subscriberIdentifier)

Raised after a key’s type is changed, for example when declaring a data key as an event.