"""
The Miso Alarm module. Provides access to some of the native Symbian OS alarm server functionality.
"""

class Alarm:
    """
    An object for managing a session-based alarm. At most one alarm per instance can be set at a time; when a new alarm is set, any old one is cancelled. The benefit/drawback of using a session-based alarm is that when the session is closed, any associated alarm is automatically removed. Use an instance of this class to have an alarm deleted when the instance is deleted, or when the owning thread dies.
    """
    def __init__(self):
        pass
    
    def set_alarm(self, callback, datetime, message, no_alert = 0):
        """
        Sets a session alarm. Any existing session alarm managed by this object is removed.
        callback:: Of type callable. A callable to call when the alarm expires, or when the alarm request is otherwise completed. An error code is passed to the callback as the sole argument.
        datetime:: Of type float. Alarm time.
        message:: Of type unicode. Alarm message. Shows in any system alert dialog.
        no_alert:: Of type int. Defaults to value 0. A true value indicates that there should be no system alert upon alarm expiration.
        """
        pass
    
    def unset_alarm(self):
        """
        Removes any outstanding session alarm that has been set via this object.
        """
        pass

def add_alarm(datetime, message):
    """
    Adds a non-session alarm to the alarm server. This will not be tied to any session, and may hence remain even after the setting process has exited. The set alarm can be deleted later by the same or different process, assuming one knows the ID of the alarm. If not, there still is the option of calling remove_all_alarms.
    datetime:: Of type float. Alarm time.
    message:: Of type unicode. Alarm message. Shown in the system alert dialog.
    Returns:: Of type int. The ID of the set alarm.
    """
    pass

def remove_alarm(alarm_id):
    """
    Deletes the specified non-session alarm.
    alarm_id:: Of type int. The ID of the alarm to delete.
    """
    pass

def remove_all_alarms():
    """
    Removes all alarms set using this library.
    """
    pass

def time_to_string(datetime):
    """
    This function takes a Unix time and converts it to text using a Symbian native formatting routine. This is mainly useful for checking that the Unix to Symbian time conversion is correct, as Python does have built-in support for formatting a time as a string.
    datetime:: Of type float. Date and time, as a float in Unix time.
    Returns:: Of type unicode. A string representation of the passed time, in local time.
    """
    pass