Introduction

Starting with v1.0a7, CarFrontEnd will support the ability for Plugins to communicate between themselves as well as with CarFrontEnd itself.

Code Support

To utilize the messaging system, you have to implement some basic code. The CarFrontEnd Plugin Messaging interface works in a similar manner to NSNotification in that you need a selector to respond to messages (if you are listening for messages), must register for messages you want to know about, and may send messages for the application or other plugins to respond to.

With v1.0a7, the -initWithPluginManager: method is added to the CarFrontEndProtocol. This method is called by the PluginManager after it loads your plugin and passes the PluginManager object as it's argument. You must store and retain this object if you wish to use the messaging interface. In the SamplePlugin code shown on the CreatePlugin wiki page, we use the owner variable to store the PluginManager object.

You must also import CarFrontEndAPI/CarFrontEndAPI.h which will load the PluginManager Protocols as well as the currently known messages.

Sending Messages

To send a message, use the -sendMessage:with: method of PluginManager.

[owner sendMessage:SomePredefinedMessage with:nil]

• SomePredefinedMessage - The message to be sent.
• nil - This is an object that will be passed to any of the observers of this message. The type and value of this argument is dependent on the message being sent (if it is needed at all).

Processing Messages

To respond to messages is slightly more difficult, but still rather simple. You will need a method to process the message(s) and will need to register for the message.

Your responder must accept two arguments. The first must be a NSString for the message and the second should be the object type (or a plain id is advised) you are expecting.

- (void) observePluginMessage: (CFEMessage) message with: (id) userInfo {
    if (CFEMessagesEqual(SomePredefinedMessage, message)]) {
        if (userInfo != nil && [userInfo isKindOfClass:[NSString class]]) {
            NSLog(@"SomePredefinedMessage: %@", userInfo);
        } else {
            NSLog(@"SomePredefinedMessage: No message supplied.");
        }
    }
}

You register your responder using the -addObserver:selector:name: method of the PluginManager. This method expects:

1. id - The object observing the message (normally self).
2. SEL - The selector of your responder method.
3. CFEMessage - The message to respond to.

[owner addObserver:self
                      selector:@selector(observePluginMessage:with:)
                          name:SomePredefinedMessage];

We advise that also remove your responder from processing when your Plugin is not the currently active plugin if your response will make UI changes that are not needed at that time.

[owner removeObserver:self name:SomePredefinedMessage];

1. id - The object that was responding to the message.
2. CFEMessage - The name of the message.

You may also remove all messages for your object at once with -removeAllObserversFor: which takes the observing object as it's only argument.

CarFrontEnd Messages

These are the messages that are built into CarFrontEnd.

Additional messages will be added over time (and should be added above), but you are free to listen for and send your own custom messages.

CFEMessage & Helper Functions

typedef struct cfe_message_struct {
    NSString    *name;      // The name of the message
    BOOL        activeOnly; // Determines if the message should be sent only
                            //  to the active plugin, or all plugins.
                            //  CFE application objects will always get the
                            //  the messages that tey observe.
} CFEMessage;

CFEMessage CFECreateMessage(NSString *name, BOOL activeOnly)

This function will return a new CFEMessage for you.

• name - The textual name of your message.
• activeOnly - YES = The message is only sent to the active plugin. NO = It is sent to all plugins.

void CFEDestroyMessage(CFEMessage message)

Does the proper cleanup on the given message.

BOOL CFEMessagesEqual(CFEMessage message1, CFEMessage2)

Tests to see if the name value of the message are equal.