HYP

@abstract The framwork’s state.

@discussion This property yields the framework’s state, indicate what kind of activity it’s performing at any given moment.

@abstract The local HYPInstance object.

@discussion This property yields the HYPInstance object associated with the domestic instance, created on the host device. This property is nil until the Hype framework is first requested to start. At that point, a local identifier is generated and the realm queried from the Info.plist file or start options. This object is then kept throughout the framework’s lifecycle.

@abstract Getter for the framework’s singleton instance.

@discussion This class method returns Hype’s singleton instance. Any attempt to instantiate this class in any other way will result in an exception being thrown. This method is thread safe and will return the same instance to all threads calling it concurrently.

@returns Hype’s singleton instance (instance of HYP).

@abstract Adds a message observer.

@discussion After being added, the message observer will get notifications for message states. Notifications will be triggered when messages are received, when they fail delivery, or when a message is delivered. If the observer has previously already been registered, it will not be registered twice, and the method will do nothing.

@abstract Removes a message observer.

@discussion This method removes a message observer (HYPMessageObserver) that was previously registered with -addHypeMessageObserver:. If the observer was not previously registered or has already been removed, this method does nothing. After being removed, the observer will no longer get any notifications from the SDK.

@abstract Adds a network observer.

@discussion Network observers get notifications for network events, such as instances being found and lost on the network. The network observer (HYPNetworkObserver) being added will get notifications after a call to this method. If the observer has already been registered, this method does nothing, and the observer will not get duplicated events.

@abstract Removes a network observer.

@discussion This method removes a previously registered network observer (HYPNetworkObserver). If the observer has not been registered or has already been removed, this method does nothing. After being removed, the observer will no longer get notifications from the SDK.

@abstract Adds a state observer.

@discussion State observers get notifications for Hype’s state and lifecycle events. If the observer has already been registered it will not be registered twice, preventing the observer from getting duplicate notifications.

@abstract Removes a state observer.

@discussion This method removes a previously registered state observer (HYPStateObserver). If the observer is not present on the registry, because it was not added or because it has already been removed, this method does nothing. After being removed, the observer will no longer get notifications from the SDK.

@abstract Starts all Hype services.

@discussion Calling this method requests the framework to start its services, by publishing itself on the network and browsing for other devices. In case of success, all observers will get a -hypeDidStart: notification, indicating that the device is somehow participating on the network. This might not mean that the device is both browsing and advertising, but that it is participating in either or both ways. In case of failure, the observers get a -hypeDidFailStarting:error: notification. This is common if all adapters are off, for instance. At that point, it’s useless trying to start the services again. Instead, the implementation should wait for an observer notification indicating that recovery is possible, with -hypeDidBecomeReady:. If the services have already been requested to run but have not succeeded nor failed (that is, the request is still being processed) this method does nothing. If the services are already running, the observers get an immediate notification indicating that the services have started as if they just did (-hypeDidStart:). The options object allows passing custom configurations, such as HYPOptionRealmKey or HYPOptionIdentifierKey. Some of this options (such as HYPOptionRealmKey) are mandatory, and the framework throws an exception if not properly set. Others are optional, and allow for fine tuning of the framework’s behaviour. Future releases will keep adding more options for further configuration abilities.

@abstract Stops all Hype services.

@discussion Calling this method requests the framework to stop its services by no longer publishing itself on the network nor browsing for other instances. This does not imply previously found instances to be lost; ongoing operations should continue and communicating with known instances should be possible, but the framework will no longer find or be found by other instances participating on the network.

@abstract Sends a message to a given instance.

@discussion This method attempts to send a message to a given instance. The instance must be a previously found and not lost instance, or else this method fails with an error. It returns immediately (non blocking), queues the data to be sent, and returns the message (HYPMessage) that was created for wrapping the data. That data structure is helpful for tracking the progress of messages as they are being sent over the network. The message or the data are not strongly kept by the framework. The data is copied and kept while it’s queued, but the memory is released as its fragments are sent. If the data is needed for later use, it should be kept at this point, or otherwise it won’t be recoverable. Messages contain an identifier which can later be used to match events with the original data. Progress notifications are issued to message observers (HYPMessageObserver). When listening to progress tracking notifications, two concepts are important to distinguish: sending and delivering. A message being sent (-hype:didSendMessage:toInstance:progress:complete:) indicates that the data was buffered, but has not necessarily arrived to its destination. Delivery (-hype:didDeliverMessage:toInstance:progress:complete:) on the other hand, indicates that the content has reached its destination and that has been acknowledged by the receiving instance. This distinction is especially important in mesh, when the proxy device may not be the same as the one the data is intended to. The trackProgress argument indicates whether to track delivery. The data being queued to the output stream (sent) is always notified, regardless of that setting. Notice that passing YES to this parameter incurs extra overhead on the network, as it implies acknowledgements from the destination back to the origin. If progress tracking is not needed, this should always be set to NO. In case an error occurs that prevents the message from reaching the destination, the delegate gets a failure notification (-hype:didFailSendingMessage:toInstance:error:) with an appropriate error message describing the reasons. If a proper reason cannot be determined, a probable one is used instead.

@returns A message wrapper containing some metadata.

@abstract Sends a message to a given instance without tracking progress.

@discussion This method calls -sendData:toInstance:trackProgress: with the progress tracking option set to NO. All other technicalities described for that method also apply.

@returns A message wrapper containing some metadata.