/simpletypesystem/trunk

/*

Copyright (c) 2013-2014 Gustav Hartvigsson

Permission is hereby granted, free of charge, to any person obtaining a copy

of this software and associated documentation files (the "Software"), to deal

in the Software without restriction, including without limitation the rights

to use, copy, modify, merge, publish, distribute, sublicense, and/or sell

copies of the Software, and to permit persons to whom the Software is

furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in

all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR

IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE

AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER

LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,

OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN

THE SOFTWARE.

*/

#pragma once

#include "defs.h"

#include "Func.h"

S_BEGIN_DECLS

/** @file

 * @defgroup SGlobalNotify SGlobalNotify

 * @addtogroup SGlobalNotify

 * @{

 *

 * SSTS provides a system for global notifications. Global notifications are

 * like signals, but have global scope, IE: there is only one SGlobalNotify

 * object that can exist in the system at any point.

 *

 * It in not possible to directly access the GlobalNotify object, and it's

 * structural stability can not be guaranteed.

 *

 * SSTS does not initialise the the GlobalNotify object until one of it's

 * function are run.

 *

 * @sa 

 */

/**

 * An opaque object.

 * It is not possible to access the data inside this object.

 */

typedef struct SGlobalNotify SGlobalNotify;

/**

 * Notify all subscribers of the to the 

 */

S_EXPORTED

void

s_global_notify (schar * name,

                 spointer user_data);

/**

 * Add a new global notification.

 *

 * @param name The name of the notification.

 *

 * @return The unique handle of the notification on success.

 * @return <0 on fail.

 *

 * @note

 * You can safely dismiss the handle for the notify.

 */

S_EXPORTED

sint

s_global_notify_add (schar * name);

/**

 * A convenience method to check if a notify name is already taken.

 * 

 * @param name The notify name to get the handle from.

 *

 * @return <0 on fail.

 * @return The numerical handle of the notify.

 */

S_EXPORTED

sint

s_global_notify_get_handle (schar * name);

/**

 * Substribe to a notify using a callback.

 *

 * @param name The name of the notify to subscribe to.

 * @param callback The callback to be triggered when a notify is sent.

 *

 * @return The unique subscription handle, this is what is used in

 *         s_global_notify_unsubscribe() to unsubscribe to a notify.

 *

 * @note

 * A notify Callback has to have the following signature:

 * <tt> void my_callback (char * name, spointer user_data) </tt>

 */

S_EXPORTED

sint

s_global_notify_subscribe (schar * name,

                           Callback callback);

/**

 * Unsubscribe to a notify.

 * 

 * @param name The name of the notify to unsubscribe to.

 * @param subscription_id The ID of the subscription.

 *

 * @returns TRUE on success

 * @returns FALSE on fail

 */

S_EXPORTED

sboolean

s_global_notify_unsubscribe (schar * name,

                             sint subscription_id);

/**

 * Teardown down the global notification system.

 *

 * This should not be called directly, use s_teardown() to instead.

 */

S_HIDDEN

void

s_global_notify_teardown ();

S_END_DECLS

/** @} */