This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

pm_add_property()

Add a property to a power managed object

Synopsis:

#include <sys/pm.h>

int pm_add_property(pm_hdl_t hdl, 
                    pm_property_t id, 
                    void *value, 
                    int size);

Arguments:

hdl: Handle to the power managed object, obtained via pm_attach().
id: An integer identifier that specifies the property type.
value: Initial value of the property.
size: Size of the property value.

Description:

The pm_add_property() adds a new property to a power managed object. The power manager policy is informed whenever properties are added to an object and when property values are modified.

Each property consists of an <id, value> pair:

id is an integer identifier for the property:

The range of values from PM_PROPERTY_USER to UINT_MAX are available for user defined properties. These user defined properties can be used to implement system specific data that can be used by the power manager policy to evaluate the most appropriate system power mode.

The range of values from 0 to PM_PROPERTY_USER-1 are reserved for Neutrino defined properties.

The value variable specifies the initial value of the property. The size and format of the data pointed to by value depend on id.

Returns:

0: Success.
-1: An error has occurred (and errno has set).

Errors:

EBADF: hdl is not a valid handle.
EEXIST: The object already has a property with the identifier id.
EACCES: Caller isn't allowed to add properties to the object (for example, hdl wasn't opened with O_RDWR access).
EFAULT: A fault occurred accessing value.
ENOMEM: Insufficient memory to allocate power manager data structures.

Examples:

#include <sys/pm.h>
#include <fcntl.h>
#include <stdlib.h>

// define a property identifier and structure containing property data
#define PROP_ID         (PM_PROPERTY_USER + 1)
struct prop_value {
   int     data1;
   int     data2;
};

int
main()
{
  pm_hdl_t                        hdl;
  struct prop_value       value = { 1, 2 };

  hdl = pm_attach("object", O_RDWR);
  if (!pm_valid_hdl(hdl)) {
     perror("pm_attach");
     return EXIT_FAILURE;
  }

  if (pm_add_property(hdl, PROP_ID, &value, sizeof value) == -1) {
     perror("pm_add_property");
     return EXIT_FAILURE;
  }

  return EXIT_SUCCESS;
}

Classification:

Neutrino

Safety:
Cancellation point	Yes
Interrupt handler	No
Signal handler	Yes
Thread	Yes