Chapter 1. Getting Started

Using Power Manager Engine's C API

Power Manager Engine provides a comprehensive C Application Programming Interface (API). The C interface underpins all the other interfaces and provides the greatest flexibility.

Before embarking on learning the C API, we recommend investigating the equivalent Objective-C API. Objective-C is easier to learn, and offers tight integration with Interface Builder to get your projects up and running quickly.

The C API uses Apple's CoreFoundation library. You are expected to be comfortable with using CoreFoundation entities and familiar with CFRunLoops. If you have used CFSockets or CFStreams before, then Power Manager Engine's API will be familiar.

There are three core C structures to learn: PMConnection, PMRequest, and PMResponse. With these three C structures you can access and manipulate any Power Manager Engine interface.

Creating a Connection

Use PMConnection to create a connection to a local or remote Power Manager Engine instance.

A PMConnection instance provides bi-directional access to a Power Manager Engine. It deals with request encoding and decoding, authentication, hostname resolution, and distributing responses as they arrive.

Creating a connection involves two steps. The first step creates a connection instance and sets up the required resources.

Example 1.1. Create a PMConnection

PMConnectionRef connection = NULL;
connection = PMConnectionCreate(kCFAllocatorDefault,CFRunLoopGetMain(),kCFRunLoopCommonModes);
assert(NULL != connection);

PMConnectionCreate returns a connection. If an error occurs, NULL is returned. Errors at this stage are unlikely but possible if memory is low.

The next step is to connect to a local or remote Power Manager Engine instance. PMConnectionConnectToURL performs the following steps:

  1. Resolves the URL's hostname

  2. Opens a connection

  3. Authenticates

These steps are all performed as part of the CFRunLoop provided during the connection's creation.

Example 1.2. Connect to the default engine

bool validConnect = PMConnectionConnectToURL(connection,NULL,NULL);
assert(true == validConnect);

PMConnectionConnectToURL returns immediately. False will be returned if the URL is malformed or network resources could not be allocated.

Passing NULL for the URL asks PMConnnection to use the default URL; this URL will connect to the local Power Manager Engine instance.

Passing NULL for the options asks PMConnection to use defaults with authenticating. Relying on defaults is fine for local connections, but remote connections need a pass phrase digest. Providing this digest will be covered shortly.

Follow the Create/Copy Rule

PME's C API follows the same memory management principles as CoreFoundation. If the API function contains Create or Copy, the caller must call Release on the returned instance. If the API function contains Get, the caller must not Release the instance.

[Note] Note

Power Manager Engine's C API conforms to Apple's CoreFoundation create/copy memory management rules.