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 <NSApplicationDelegate> {
       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).

Previously we walked through how to bind a piece of user interface to Power Manager. This time we will write a small tool that binds programmatically and runs without a graphical interface.

This recipe will highlight just how seamlessly you can integrate with Power Manager’s engine. All the networking, notifications, and requests are handled for you, all thanks to DSSWPMObserver.

Binding to the Events

We are going to create a small tool that binds an array to Power Manager’s events. The events we want to bind to those returned by the eventstore.events variable.

The resulting tool will have an NSArray of NSDictionaries managed and kept in sync with Power Manager’s events. As changes occur in Power Manager’s events, those changes will be instantly and automatically reflected in the tool.

1. Create a new command line project in Xcode 4.
   
   

   Create a new command line project in Xcode.

2. Select the Foundation type of project; this includes the Foundation framework.
   

   Select the Foundation type of project.

3. Add the PowerManager.framework to your project.
4. Copy and paste the following code into your main.m file:

   #import <Cocoa/Cocoa.h>
   #import <PowerManager/PowerManager.h>
   
   @interface Bound : NSObject {
       NSArray* events;
   }
   @property (retain) DSSWPMConnection* connection;
   @property (retain) DSSWPMObserver* observer;
   @property (retain) NSArray* events;
   @end
   
   @implementation Bound
   @synthesize connection;
   @synthesize observer;
   
   - (id)init
   {
       if (self = [super init])
       {
           self.connection = DSSWPMConnection.connection;
           self.connection.keepAlive = YES; // Stop idle connections disconnecting
           self.connection.autoReconnect = YES; // Reconnect if connection dropped
   
           self.observer = [[[DSSWPMObserver alloc] initWithConnection:connection] autorelease];
   
           // Bind the events in this object to Power Manager's eventstore.events
           [self bind:@"events" toObject:self.observer withKeyPath:(NSString*)kPMRPCEventStoreEvents options:nil];
       }
       return self;
   }
   
   - (void)dealloc
   {
       [self unbind:@"events"];
       self.events = nil;
       self.observer = nil;
       self.connection = nil;
       [super dealloc];
   }
   
   - (NSArray*)events
   {
       return [[events retain] autorelease];
   }
   
   - (void)setEvents:(NSArray *)inEvents
   {
       if (inEvents != events)
       {
           [events release];
           events = [inEvents retain];
   
           // Print a list of the event names
           NSLog(@"setEvents called with %d events:",(int)events.count);
           for(NSDictionary* event in events)
           {
               NSLog(@"- %@",[event objectForKey:(NSString*)kPMEventName]);
           }
       }
   }
   
   @end
   
   int main(int argc, const char * argv[])
   {
       @autoreleasepool {
           Bound* bound = [[Bound alloc] init];
   
           // Run until terminated
           [[NSRunLoop mainRunLoop] run];
   
           [bound release];
       }
       return 0;
   }

5. Build and run the project.

With the tool running add, edit, and remove events from Power Manager. The tool will automatically print an updated list of events with each change.

The command line tool prints the names of your Power Manager events.

This code works by setting up an association between your local bound object with the corresponding eventstore.events variable being managed by Power Manager. The DSSWPMObserver object is responsible for performing the steps required to make this happen.

You can use this technique to bind to any variable provided by the Power Manager SDK.

The Power Manager SDK includes the DSSWPMObserver object. This Objective-C/Cocoa object is wonderful because it makes writing responsive energy saving tools easy.

The process of observing changes is called Key Value Observation (KVO). Understanding and using KVO is a core feature of developing in Objective-C/Cocoa on the Mac and on iOS.

Typically KVO is used within an application. For Power Manager, we have extended KVO to work with any Power Manager connection, including those connected over a network. The same code that observes a change in Power Manager events on your Mac will work for observing changes in events on a remote Mac located on the other side of the planet. The networking is dealt with for you.

Let’s jump into how to use Power Manager SDK’s Key Value Observation support. We will do this by extending the connecting recipe’s Xcode project.

This example will require no new code. The observation binding will be done entirely using Xcode’s user interface tools.

Binding to Power Manager

Follow the steps in the connecting recipe to create a Power Manager aware project.

Your Objective-C Xcode project has a Power Manager connection and observer created in the application delegate. We are going to bind a label in the user interface to this observer.

1. Select the MainMenu.xib in Xcode.
2. Click on the Window object within the xib.
3. Add a new label to the window.
4. Bind the label’s value to the application delegate object:
   • Bind To: Test App Delegate
   • Model Key Path: self.observer.scheduler.enabled
   

   Bind the label to the application delegate obsever.

   

   Add the KVO path of the value you want to observe.

5. Build and run the project.

The running application will show a window with either a 1 or a 0 for the label. It may not immediately seem exciting, but try starting and stopping Power Manager.

The test application updates instantly as Power Manager changes.

Your label will change to 1 when Power Manager is running, and 0 when Power Manager is stopped. This happens automatically and instantly thanks to the observation you created.

Try changing the Model Key Path to one of the following:

• self.observer.build.version
• self.observer.client.computername
• self.observer.eventstore.events

Every variable in the Power Manager Application Programmer Interface (API) can be bound to and observed.

Thanks to the DSSWPMObserver object you can use Objective-C/Cocoa’s KVO mechanism to build responsive interfaces with very little code.

The Power Manager SDK is included as standard with Power Manager. There are no additional tools, software, or licences to deal with in order to start using the Power Manager SDK.

Let’s walk through the steps needed to create a connection from your program to Power Manager. We are going to use Xcode 4 and Objective-C/Cocoa for this example.

Create an Xcode Project

We need a project to add Power Manager support to. I recommend starting a small test project to experiment with first. You can later add Power Manager to existing projects.

1. Create a new project with Xcode: File > New > Project…
2. Select the Cocoa Application project template.
3. Work through Xcode’s project creation steps.

Add the Power Manager Framework

We need to add the PowerManager.framework to our Xcode project. This framework includes everything you need to connect with Power Manager.

1. Navigate to the project’s Build Phases in Xcode.
   

   Within Xcode, navigate to your project's Build Phases.

2. In the Link Binary With Libraries phase, click + to add a library.
   

   Add the framework called PowerManager.framework

3. Add the PowerManager.framework.
   

   The Power Manager framework should now be listed and linked during builds.

If the PowerManager.framework is not listed, look for the framework in the folder /Library/Frameworks/. If the framework is missing, install Power Manager on your Mac.

Create a Connection

With the framework added to your project, you can now connect to Power Manager.

For this experiment, let’s add a Power Manager connection to the project’s application delegate. This is an object created when the application is launched. The files for this object should have been created by Xcode for you.

Look for a pair of files ending with AppDelegate; in my case, the file name is DSSWTestAppDelegate.

We are going to add a few bits and pieces to both the header (.h) and body (.m) files. Let’s look at the finished DSSWTestAppDelegate.h first:

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

@interface DSSWTestAppDelegate : NSObject <NSApplicationDelegate>

@property (assign) IBOutlet NSWindow *window;
@property (retain) DSSWPMConnection *connection;
@property (retain) DSSWPMObserver *observer;

@end

In the header file:

• I have added an import to open up access to the contents of PowerManager.framework.
• I have added declarations for two new properties; a connection and an observer.

Let’s look at the finished DSSWTestAppDelegate.m next:

#import "DSSWTestAppDelegate.h"

@implementation DSSWTestAppDelegate

@synthesize window = _window;
@synthesize connection;
@synthesize observer;

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

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

@end

In the body file:

• I have added synthesize entries for the connection and observer.
• I instigate the connection and observer when the application launches.
• I nullify the connection and observer when the application delegate is deallocated.

This small body of code is all you need in order to set up and maintain a connection to Power Manager running on your Mac.

Next learn how to observe changes in Power Manager.

In a busy environment, such as a lab or business, being able to ensure the Mac’s volume is set at a reasonable level when a user logs in is essential.

You can programmatically change a Mac’s system volume through AppleScript. We are going to use this ability to create an event in Power Manager. The event will be triggered when a user logs in, and will perform a small volume setting AppleScript.

Let’s walk through how to create a log in triggered AppleScript.

Create a Run AppleScript at Log In Event

We are going to divide this recipe into two sections. The first will use the Schedule Assistant to create a daily AppleScript event, and finally we will modify this event by adding a log in trigger.

Create a Daily AppleScript Event

1. Launch System Preferences and select Power Manager.
2. Click Add… to create a new event.
   

   Click the Add button to create a new Power Manager event.

3. Choose the template Run a script daily.
   

   Choose the Run script daily task.

4. Click Continue to the Script step.

5. Copy and paste the following into the Script to run text box:

   #!/bin/sh
   
   osascript -e "set Volume 3"

   The volume can be set to a number between 0 (silent) and 10 (loudest).

   

   Copy and paste in the set volume AppleScript.

6. Click Continue until you reach the Why step. There is nothing to change in the When and Constraints steps.
7. Give the event a title and add a note about the purpose of the event in the Why step.
   

   Give your new event a name and add notes about its purpose.

8. Click Continue and then Add to create the new event.
   

   Click Add to confirm and create the new Power Manager event.

   

   An event to set the volume once a day has been created.

An event containing the volume setting AppleScript has now been created. This event is set to trigger once a day.

Add a Log In Trigger to the Event

We need to modify the event to trigger when a user logs in, instead of performing once a day. To do this, we are going to use the event editor.

1. Open the event in the event editor; hold down the Option and double-click on your event.
   

   Double-click the event with the Option key held down.

2. Delete the daily trigger; select the Trigger’s Action cog > Delete….
   

   Delete the existing Daily Trigger using the Action pop-up menu.

   

   The event after the Daily Trigger has been deleted.

3. Add a log in trigger; select Add a trigger > Log In.
   

   Add a Log In trigger using the Add a trigger pop-up menu.

4. Click Save to save the changes to the event.
   

   Set volume event with the Log In trigger added.

   

   The new set volume Power Manager event is ready.

Your new Power Manager event to set the volume is now ready and will perform each time a user logs in.

Many of the problems with automatically shutting down your computer come from poorly behaved applications or from applications stalling while they wait for some form of interaction.

There are two basic approaches to automatically shutting down your Mac. The first is to issue a shut down AppleEvent. The second method is to use the command line tool shutdown.

Of these two methods, Apple recommends the first. In Q&A1134, Apple Developer Technical Support (DTS) recommend asking the System process to shut down through the kAEShutDown AppleEvent. This method mirrors what happens when you select Shut Down from the Finder’s Apple menu.

Shut Down with kAEShutDown

Sending an AppleEvent to the System process requesting a shut down should completely power down your Mac. If all is well, your Mac will shut down in an orderly manner.

Problems arise with applications that need some interaction when they quit. Unsaved changes and running tasks that need to be stopped often end in dialog boxes asking where to save documents and “are you sure” alerts. These alerts will typically stop the shut down; in most cases leaving your Mac sitting with some applications quit and others still running.

With Mac OS X 10.7, aka Lion, Apple is moving towards an operating system design that can deal with applications seamlessly quitting and relaunching without user interaction. The design is not yet perfect and does not deal with every contingency but it is a step forward.

It is at this stage that problematic applications prompt people to look at the second shut down method. The second method is shutting down using the command line tool shutdown.

shutdown -h now

shutdown is a blunt tool that will in most cases shut down your Mac. It works at a layer below the Mac’s user interface and is roughly the equivalent of force quitting everything.

With shutdown, Mac applications that would have quit nicely are not given the chance. In most cases using shutdown should be fine but care needs to be taken about denying applications of the opportunity to quit nicely.

Power Manager

Power Manager has evolved to do its very best to shut down your Mac in a Mac friendly way. Power Manager will force quit applications that threaten to block the automated shut down, but the force quit is only used after the application has been issued a friendly quit request.

Let’s walk through what happens when you ask Power Manager to shut down your Mac.

Power Manager is multiple user savvy and first deals with the logged in users. The following steps happen within each logged in user’s session:

1. Running applications are sent a quit request.
2. Running applications are given time to quit.
3. If an application has not quit in time, the application is force quit.
4. With all the applications quit, the user is logged out.

Once all the users are logged out, Power Manager then asks Mac OS X to shut down. You can watch this sequence play out in the transcripts of the Mac’s system.log file.

Power Manager’s shut down process is reliable, predictable, and Mac friendly.

System Folder Applications

There is one exception where Power Manager will not shut down your Mac. Power Manager will not force quit an application that lives within the /System folder. The contents of this folder are managed by Apple.

If an application within the System folder wants to stop your Mac shutting down, we decided it should be respected. Apple’s applications should be ideal Mac citizens and quit properly when requested; if they do not, then it hints at underlying problems that need to be addressed rather than masked.

A Fine Balance

Automatically shutting down your Mac is possible. Shutting down safely and predictably just takes some effort to get right.

Power Manager‘s approach is to allow Mac OS X to handle as much as possible. Where needed, Power Manager applies a light touch to make sure that applications that might cause problems are dealt with first.

Power Manager includes a built-in task that will make your Mac shut down safely after a period of inactivity. Let’s walk through how to create this task.

Create a Shut Down After Inactivity Event

1. Launch System Preferences and select Power Manager.
2. Click Add… to create a new event.
   

   Click Add to start creating the shut down event in Power Manager

3. Choose the template Power off after inactivity.
   

   Select the "Power off after inactivity" task for your new event

4. Click Continue to the What and When step.
5. By default, the event will Sleep after 15 minutes. Adjust the action to Shut Down and the required period of inactivity to match your needs.
   

   Adjust the event's action and inactivity duration.

6. Continue through the remaining steps until your event is created.
   

   Continue through the Time Constraints

   

   Continue through the Interactive Constraints

   

   Use the Why step to name and describe your new event

   

   Finally confirm your new Power Manager event

Having followed the steps above, you will have created a new event in Power Manager. This event will start working immediately and will shut down your Mac after a period of inactivity.

Your new shut down after inactivity event is ready and scheduled

Remember that unsaved changes may be lost if you let your Mac shut down automatically. Always save changes before leaving your Mac unattended.

This ability is included as standard with Mac OS X. It has limitations but for many this will be enough to start saving energy.

Let’s walk through how to schedule your Mac to sleep, shut down, or restart at a specific time.

Energy Saver’s Schedule

1. Launch System Preferences > Energy Saver
   
   

   Open Energy Saver in Mac OS X's System Preferences

2. Click on the Schedule… button in the lower-right.
   

   Energy Saver's Schedule options

3. Enable the check box next to Sleep to activate the ability.

4. Use the pop-up menus and time to set up your event.

   The action menu includes:

   • Sleep
   • Shut Down
   • Restart
   

   Energy Saver can sleep, shut down, and restart the Mac

   The days menu includes:

   • Weekdays
   • Weekends
   • Every Day
   • Monday
   • Tuesday
   • Wednesday
   • Thursday
   • Friday
   • Saturday
   • Sunday
   

   Energy Saver offers a limited range of days

5. Click OK to apply your energy saving event.

There are limitations to what can be achieved with Energy Saver’s Schedule. The user interface only permits a restricted range of event times and days.

If you need more capabilities or want to expand your energy saving schedule, you can turn to the built-in command line tool pmset.

pmset exposes more of Mac OS X’s capabilities and lets you create more complex schedules. Schedules are still limited in scope, but it offers more than the Energy Saver.

If you need more control and capabilities, try our energy saving Power Manager software.

Let’s walk through how to schedule a shell script to run after a user logs out of Mac OS X. Our shell script is going to be very simple but you can make yours as complex as needs be.

We are going to start by using the Schedule Assistant built into Power Manager and then we are going to customise the event using the Event Editor.

Scheduling a Log Out Shell Script

1. Launch System Preferences and select Power Manager.
2. Click Add… to create a new event.
   

   Launch Power Manager and click the Add button

3. Choose the template Run a script.
   

   Select the Run a Script task in the Schedule Assistant

4. Click Continue to the Script step.

5. Copy and paste your shell script into the Script step.

   #!/bin/sh
   
   touch /tmp/lastlogout.txt

   The shell script can be run as the root user, as a normal user, or even as whoever is currently logged in at the time. For this script, we have set the Environment to Super User (root).

   

   Copy and paste in your shell script

6. Click Continue to the When step.
7. Adjust the time and date to the distant future; this trigger will be replaced in a later step.
   

   Change the date to a time in the future

8. Continue through the remaining steps until your event is created.

   

   Continue passed the Constraints step

   

   Name and description your Power Manager event

   

   Confirm the event and click Add

   With these steps completed, you will have a basic Power Manager event queued up. This event includes your shell script but is not yet triggered after log out.

   

   The event has been created but is not yet finished

   Let’s customise this event using the Event Editor. We want to replace the Date and Time based trigger with a Log Out trigger.

9. Hold down the Option key on the keyboard and double-click on your event; the Event Editor will now appear.
   

   Your event in Power Manager's Event Editor

10. Delete the existing Date and Time trigger; use the Action cog and select Delete….
    

    Delete the date and time trigger from the event

    

    The event with the date and time triggered deleted

11. Add a new Log Out trigger; use the Add a trigger pop-up menu and select Log Out.
    

    Add a Log Out trigger to your event

12. Click Save to save your changes and finish editing the event.
    

    Click Save to save the changes and close the Event Editor

The finished event to run a shell script after log out is ready

Your new Power Manager event is ready and will now run every time a user logs out.

Sleep Monitor 3 recommended by For Mac Eyes Only

Eric’s review is detailed and covers Sleep Monitor‘s capabilities well. I was pleased to see the AppleScript interface provided an answer for one potential short coming.

One aspect Eric raised was the missing ability to export your data. This is possible to do with Sleep Monitor; you can export all your gathered information using the File > Export… menu item. Sleep Monitor can export your data in RTF, plain text, Word, and XML formats. The plain text export is tab separated, so can be imported directly into a spreadsheet.

A free 30 day demonstration of Sleep Monitor is available to download and try now.