# SoftBank Robotics documentation What's new in NAOqi 2.8?

# ALMemory API

NAOqi Core - Overview | API | Tutorial

Namespace : AL

    #include <alproxies/almemoryproxy.h>

## Method list

As any module, this module inherits methods from ALModule API. It also has the following specific methods:

class `ALMemoryProxy`

- `ALMemoryProxy::declareEvent`
- `ALMemoryProxy::getData`
- `ALMemoryProxy::getDataList`
- `ALMemoryProxy::getDataListName`
- `ALMemoryProxy::getDataOnChange`
- `ALMemoryProxy::getDataPtr`
- `ALMemoryProxy::getIntPtr`
- `ALMemoryProxy::getFloatPtr`
- `ALMemoryProxy::getDescriptionList`
- `ALMemoryProxy::getEventHistory`
- `ALMemoryProxy::getEventList`
- `ALMemoryProxy::getExtractorEvent`
- `ALMemoryProxy::getListData`
- `ALMemoryProxy::getMicroEventList`
- `ALMemoryProxy::getSubscribers`
- `ALMemoryProxy::getType`
- `ALMemoryProxy::getTimestamp`
- `ALMemoryProxy::insertData`
- `ALMemoryProxy::insertListData`
- `ALMemoryProxy::raiseEvent`
- `ALMemoryProxy::raiseMicroEvent`
- `ALMemoryProxy::removeData`
- `ALMemoryProxy::removeMicroEvent`
- `ALMemoryProxy::setDescription`
- `ALMemoryProxy::subscribeToEvent`
- `ALMemoryProxy::subscribeToMicroEvent`
- `ALMemoryProxy::unregisterModuleReference`
- `ALMemoryProxy::unsubscribeToEvent`
- `ALMemoryProxy::unsubscribeToMicroEvent`
- `ALMemoryProxy::subscriber`

## Event list

- `NAOqiReady()`
- `ALMemory/KeyAdded()`
- `ALMemory/KeyRemoved()`
- `ALMemory/KeyTypeChanged()`

## 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 a 32 bits 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

int* `ALMemoryProxy::``getIntPtr`(const std::string& key)

  Gets a pointer to an int data item, inserting a data item if needed. Throw if the data item has not the expected type. Only meaningful when called from code running in the same process as ALMemory. 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 to int

float* `ALMemoryProxy::``getFloatPtr`(const std::string& key)

  Gets a pointer to a float data item, inserting a data item if needed. Throw if the data item has not the expected type. Only meaningful when called from code running in the same process as ALMemory. 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 to float

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.

Glossary Site map Index Support Contact Legal Notices