Sending Requests with the Power Manager SDK

You can create tools and utilities that interact with Power Manager. Your software can send Power Manager requests asking for events to be performed, variables to be set, and schedules to be changed.

You can create tools and utilities that interact with Power Manager. Your software can send Power Manager requests asking for events to be performed, variables to be set, and schedules to be changed.

Previously, we have seen how to observe and bind to the Power Manager engine. These techniques are essential for monitoring and learning about what the energy saving engine is doing.

Let’s now focus on how to ask the engine to change its state on our behalf. We are going to create a button in Objective-C/Cocoa and have that button stop the scheduler.

The request we are going to use is scheduler.setenabled. This request takes a parameter called enabled. Our button will send the request with a single parameter set to NO.

Sending a Request to Power Manager

  1. Create a new Cocoa Application project in Xcode.

    Create a new Cocoa Application project in Xcode.

    Set up the new Cocoa application.

  2. Add the PowerManager.framework.

  3. Copy and paste the following into your application delegate header (h):

    #import <Cocoa/Cocoa.h>
#import <PowerManager/PowerManager.h>

@interface DSSWExampleAppDelegate : NSObject  {
    DSSWPMConnection *connection;
}
@property (assign) IBOutlet NSWindow *window;
@property (retain) DSSWPMConnection *connection;

- (IBAction)requestSchedulerStop:(id)inSender;

@end

  4. Copy and paste the following into your application delegate body (m):

    #import "DSSWExampleAppDelegate.h"

@interface DSSWExampleAppDelegate (PowerManager)
- (void)connection:(DSSWPMConnection*)connection didRespond:(DSSWPMResponse*)response;
@end

@implementation DSSWExampleAppDelegate
@synthesize window = _window;
@synthesize connection;

- (void)dealloc
{
    self.connection = nil;
    [super dealloc];
}

- (void)applicationDidFinishLaunching:(NSNotification *)aNotification
{
    self.connection = [DSSWPMConnection connection];
    self.connection.keepAlive = YES;
    self.connection.autoReconnect = YES;
}

- (IBAction)requestSchedulerStop:(id)inSender
{
    // Create a request
    DSSWPMRequest* schedulerSetRequest = [DSSWPMRequest requestWithRequest:kPMRPCSchedulerSetEnabled value:[NSNumber numberWithBool:NO] forParameter:kPMRPCParameterEnabled];

    // Send the request
    BOOL validSend = [self.connection send:schedulerSetRequest withTarget:self selector:@selector(connection:didRespond:)];
    NSAssert(validSend,@"Send failed");
}

@end

@implementation DSSWExampleAppDelegate (PowerManager)

- (void)connection:(DSSWPMConnection*)connection didRespond:(DSSWPMResponse*)response
{
    // Add your code to deal with errors or problems
    NSLog(@"Send replied: %d",(int)response.status);
}

@end

  5. View the MainMenu.xib file and add a button.

  6. Connect the new button’s action with the requestSchedulerStop: method of the application delegate.

    Connect the button to the requestSchedulerStop method.

  7. Build and run the application.

With the application running, open Power Manager so you can see the effect of your request. Click on the button and immediately Power Manager’s scheduler will stop.

You can click the button as many times as you like. Each request will be sent and successfully acknowledged. If Power Manager’s scheduler already stopped, nothing will change.

Simple but functional application to stop Power Manager’s scheduler.

Walking Through the Code

The code in this application is fairly simple despite dealing with interprocess communication and asynchronous requests. Let’s look at what happens when you launch your application and when you press the button.

Launching the Application

On launch, the application delegate creates a new connection to Power Manager. The connection is made with a local copy of Power Manager running on your Mac.

self.connection = [DSSWPMConnection connection];
self.connection.keepAlive = YES;
self.connection.autoReconnect = YES;

Note that the connection is automatically retained by the application delegate. This behaviour is declared as part of the @property line in the class’s interface.

The connection is configured to keep alive and automatically reconnect. These two settings are optional but useful.

The keepAlive setting ensures idle connections are not disconnected by Power Manager. Connections may still be disconnected but our application asks nicely to stay connected for as long as possible.

The autoReconnect setting tells the connection object to automatically establish a new connection to Power Manager should we get disconnected.

These three lines complete the set up of the connection to Power Manager. There is nothing more you need to do to manage the connection.

Clicking the Button

When you click the button, the method requestSchedulerStop: is called.

This short method does two things. It creates a request using DSSWPMRequest. It sends the request using the connection created at launch.

The sending of the request returns a boolean value. This value tells you if the request has been sent, or at least queued up for sending, successfully. Most of the time the returned boolean value will be positive (YES). A negative return value (NO) indicates a problem with the connection.

The return value has nothing to do with the state of your actual request.

When the requestSchedulerStop: method is finished, you have created and sent your request but you do not know if it succeed or not.

The request requires a moment to be sent through the connection to Power Manager, acted upon within Power Manager, and then a reply sent back from Power Manager to your application. The time it takes for this to happen is unknown; you could be talking to a computer on the other side of the world which would take much longer than requesting changes on your local Mac.

So how does the reply come back to your application? When the request was sent, a target and method were provided to the connection. It is through this pair, that you learn the fate of the request.

The connection will call the method you provided when a reply comes back. In our case, the method is connection:didRespond:. Within this method you can determine the outcome of the request and deal with any information returned.

There are numerous requests available. You have complete access to Power Manager’s energy saving engine through the Application Programming Interface (API).