// // ConnectIQ.h // ConnectIQ // // Copyright (c) 2014 Garmin. All rights reserved. // #import #import "IQConstants.h" #import "IQDevice.h" #import "IQApp.h" // -------------------------------------------------------------------------------- #pragma mark - PUBLIC TYPES // -------------------------------------------------------------------------------- /// @brief SendMessage progress callback block /// /// @param sentBytes The number of bytes that have been successfully transferred /// to the device so far for this connection. /// @param totalBytes The total number of bytes to transfer for this connection. typedef void (^IQSendMessageProgress)(uint32_t sentBytes, uint32_t totalBytes); /// @brief SendMessage completion callback block /// /// @param result The result of the SendMessage operation. typedef void (^IQSendMessageCompletion)(IQSendMessageResult result); /// @brief Conforming to the IQUIOverrideDelegate protocol indicates that an /// object handles one or more events triggered by the ConnectIQ SDK that /// require user input. @protocol IQUIOverrideDelegate @optional /// @brief Called by the ConnectIQ SDK when an action has been requested that /// requires Garmin Connect Mobile to be installed. /// /// The receiver should choose whether or not to launch the Apple App /// Store page for GCM, ideally by presenting the user with a choice. /// /// If the receiver of this message decides to install GCM, it must call /// showAppStoreForConnectMobile. - (void)needsToInstallConnectMobile; @end /// @brief Conforming to the IQDeviceEventDelegate protocol indicates that an /// object handles ConnectIQ device status events. @protocol IQDeviceEventDelegate @optional /// @brief Called by the ConnectIQ SDK when an IQDevice's connection status has /// changed. /// /// @param device The IQDevice whose status changed. /// @param status The new status of the device. - (void)deviceStatusChanged:(IQDevice *)device status:(IQDeviceStatus)status; @end /// @brief Conforming to the IQAppMessageDelegate protocol indicates that an /// object handles messages from ConnectIQ apps on compatible devices. @protocol IQAppMessageDelegate @optional /// @brief Called by the ConnectIQ SDK when a message is received from a device. /// /// @param message The message that was received. /// @param app The device app that sent the message. - (void)receivedMessage:(id)message fromApp:(IQApp *)app; @end // -------------------------------------------------------------------------------- #pragma mark - CLASS DEFINITION // -------------------------------------------------------------------------------- /// @brief The root of the ConnectIQ SDK API. @interface ConnectIQ : NSObject + (instancetype)new NS_UNAVAILABLE; - (instancetype)init NS_UNAVAILABLE; // -------------------------------------------------------------------------------- #pragma mark - SINGLETON ACCESS // -------------------------------------------------------------------------------- /// @brief Exposes the single static instance of the ConnectIQ class. /// /// @return The single status instance of the ConnectIQ class. + (ConnectIQ *)sharedInstance; // -------------------------------------------------------------------------------- #pragma mark - INITIALIZATION // -------------------------------------------------------------------------------- /// @brief Initializes the ConnectIQ SDK with startup parameters necessary for /// its operation. /// /// @param urlScheme The URL scheme for this companion app. When Garmin Connect /// Mobile is launched, it will return to the companion app by /// launching a URL with this scheme. /// @param delegate The delegate that the SDK will use for notifying the /// companion app about events that require user input. If this /// is nil, the SDK's default UI will be used. - (void)initializeWithUrlScheme:(NSString *)urlScheme uiOverrideDelegate:(id)delegate; // -------------------------------------------------------------------------------- #pragma mark - EXTERNAL LAUNCHING // -------------------------------------------------------------------------------- /// @brief Launches the Apple App Store page for the Garmin Connect Mobile app. /// The companion app should only call this in response to a /// needsToInstallConnectMobile event that gets triggered on the /// IQUIOverrideDelegate. - (void)showAppStoreForConnectMobile; /// @brief Launches Garmin Connect Mobile for the purpose of retrieving a list of /// ConnectIQ-compatible devices. /// /// Once the user has chosen which ConnectIQ devices to share with the /// companion app, GCM will return those devices to the companion app by /// opening a URL with the scheme registered in /// initializeWithUrlScheme:uiOverrideDelegate:. /// /// The companion app should handle this URL by passing it in to the /// parseDeviceSelectionResponseFromURL: method to get the list of devices /// that the user permitted the companion app to communicate with. - (void)showConnectIQDeviceSelection; /// @brief Parses a URL opened from Garmin Connect Mobile into a list of devices. /// /// @param url The URL to parse. /// /// @return An array of IQDevice objects representing the ConnectIQ-compatible /// devices that the user allowed GCM to share with the companion app. /// /// @seealso showConnectIQDeviceSelection - (NSArray *)parseDeviceSelectionResponseFromURL:(NSURL *)url; /// @brief Launches Garmin Connect Mobile and shows the ConnectIQ app store page /// for the given app. /// /// The companion app should call this if the user would like to manage /// the app on the device, such as to install, upgrade, uninstall, or /// modify settings. /// /// @param app The app to show the ConnectIQ app store page for. - (void)showConnectIQStoreForApp:(IQApp *)app; // -------------------------------------------------------------------------------- #pragma mark - DEVICE MANAGEMENT // -------------------------------------------------------------------------------- /// @brief Registers an object as a listener for ConnectIQ device status events. /// /// A device may have multiple device event listeners if this method is /// called more than once. /// /// @param device A device to listen for status events from. /// @param delegate The listener which will receive status events for this device. - (void)registerForDeviceEvents:(IQDevice *)device delegate:(id)delegate; /// @brief Unregisters a listener for a specific device. /// /// @param device The device to unregister the listener for. /// @param delegate The listener to remove from the device. - (void)unregisterForDeviceEvents:(IQDevice *)device delegate:(id)delegate; /// @brief Unregisters the specified listener from all devices for which it had /// previously been registered. /// /// @param delegate The listener to unregister. - (void)unregisterForAllDeviceEvents:(id)delegate; /// @brief Gets the current connection status of a device. /// /// The device must have been registered for event notifications by /// calling registerForDeviceEvents:delegate: or this method will return /// IQDeviceStatus_InvalidDevice. /// /// @param device The device to get the status for. /// /// @return The device's current connection status. - (IQDeviceStatus)getDeviceStatus:(IQDevice *)device; // -------------------------------------------------------------------------------- #pragma mark - APP MANAGEMENT // -------------------------------------------------------------------------------- /// @brief Begins getting the status of an app on a device. This method returns /// immediately. /// /// @param app The IQApp to get the status for. /// @param completion The completion block that will be triggered when the device /// status operation is complete. - (void)getAppStatus:(IQApp *)app completion:(void(^)(IQAppStatus *appStatus))completion; /// @brief Registers an object as a listener for ConnectIQ messages from an app /// on a device. /// /// An app may have multiple message listeners if this method is called /// more than once. /// /// @param app The app to listen for messages from. /// @param delegate The listener which will receive messages for this app. - (void)registerForAppMessages:(IQApp *)app delegate:(id)delegate; /// @brief Unregisters a listener for a specific app. /// /// @param app The app to unregister a listener for. /// @param delegate The listener to remove from the app. - (void)unregisterForAppMessages:(IQApp *)app delegate:(id)delegate; /// @brief Unregisters all previously registered apps for a specific listener. /// /// @param delegate The listener to unregister. - (void)unregisterForAllAppMessages:(id)delegate; /// @brief Begins sending a message to an app. This method returns immediately. /// /// @param message The message to send to the app. This message must be one of /// the following types: NSString, NSNumber, NSNull, NSArray, /// or NSDictionary. Arrays and dictionaries may be nested. /// @param app The app to send the message to. /// @param progress A progress block that will be triggered periodically /// throughout the transfer. This is guaranteed to be triggered /// at least once. /// @param completion A completion block that will be triggered when the send /// message operation is complete. - (void)sendMessage:(id)message toApp:(IQApp *)app progress:(IQSendMessageProgress)progress completion:(IQSendMessageCompletion)completion; /// @brief Sends an open app request message request to the device. This method returns immediately. /// /// @param app The app to open. /// @param completion A completion block that will be triggered when the send /// message operation is complete. - (void)openAppRequest:(IQApp *)app completion:(IQSendMessageCompletion)completion; // TODO *** Holding off on documenting this until this method actually works. - (void)sendImage:(NSData *)bitmap toApp:(IQApp *)app progress:(IQSendMessageProgress)progress completion:(IQSendMessageCompletion)completion; @end