4 * Copyright (c) 2000 - 2011 Samsung Electronics Co., Ltd. All rights reserved.
6 * Contact: Jayoun Lee <airjany@samsung.com>, Sewook Park <sewook7.park@samsung.com>,
7 * Jaeho Lee <jaeho81.lee@samsung.com>
9 * Licensed under the Apache License, Version 2.0 (the "License");
10 * you may not use this file except in compliance with the License.
11 * You may obtain a copy of the License at
13 * http://www.apache.org/licenses/LICENSE-2.0
15 * Unless required by applicable law or agreed to in writing, software
16 * distributed under the License is distributed on an "AS IS" BASIS,
17 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18 * See the License for the specific language governing permissions and
19 * limitations under the License.
29 * @addtogroup APPLICATION_FRAMEWORK
32 * @defgroup HEYNOTI HEY(ligHt Easy speedY) Notification
33 * @brief HEY(ligHt Easy speedY) Notification
35 * @section Header To use Them:
37 * #include <heynoti.h>
41 * - Light, Easy and speedy notification (in other words, HEY - ligHt Easy speedY)
43 * - Simple notification based on inotify
45 * @section example Simple Example
51 void callback(void *data)
53 printf("I got a testnoti\n");
56 int main(int argc, const char *argv[])
61 if((fd = heynoti_init()) < 0) {
62 fprintf(stderr, "heynoti_init FAIL\n");
65 printf("heynoti_init OK\n");
67 if(heynoti_subscribe(fd, "test_testnoti", callback, NULL))
68 fprintf(stderr, "heynoti_subscribe FAIL\n");
70 printf("heynoti_subscribe OK\n");
72 if(heynoti_attach_handler(fd))
73 fprintf(stderr, "heynoti_attach_handler FAIL\n");
75 printf("heynoti_attach_handler OK\n");
77 loop = g_main_loop_new(NULL, FALSE);
78 g_main_loop_run(loop);
81 g_main_loop_unref(loop);
93 #include <sys/types.h>
94 #include <sys/inotify.h>
100 /************************************************
101 * API for Notification *
102 ************************************************/
106 * Initialize the notify service\n
107 * Get file descriptor associated with a new inotify event queue.\n
110 * This API is used for initializing notify service.
112 * \par Typical use case:
113 * If user want to initialize notify service, he(or she) can use this API.
115 * \par Important notes:
118 * \return Return Type (int) \n
119 * - fd - fild descriptor. \n
120 * - -1 - fail to create file descriptor. \n
122 * \par Prospective clients:
125 * \par Related functions:
130 * \see heynoti_close()
135 * #include <heynoti.h> //Include heynoti.h file
138 * int fd = heynoti_init(); //Initialize heynoti
141 * printf("heynoti_init() failed\n");
142 * return; //return if unavailable file descriptor is returned
148 /*================================================================================================*/
149 int heynoti_init(void);
153 * Finalizes notification service\n
154 * Close the file descriptor and remove handler related fd.\n
157 * This API is used for finalizing notify service.
159 * \par Typical use case:
160 * If user want to finalize notify service, he(or she) can use this API.
162 * \par Important notes:
165 * \param fd [in] file descriptor that is created by calling heynoti_ini().
167 * \par Prospective clients:
170 * \par Related functions:
173 * \pre heynoti_init()
175 * \see heynoti_init()
180 * #include <heynoti.h> //Include heynoti.h file
182 * int fd = heynoti_init(); //Initialize heynoti
185 * fprintf(stderr, "heynoti_init fail, error_code: %d\n", fd);
186 * return; //return if unavailable file descriptor is returned
189 * heynoti_close(fd); //Finalize heynoti
193 /*================================================================================================*/
194 void heynoti_close(int fd);
198 * Register a new notification callback function with noti name\n
201 * This API is used for registering a new notification callback function with noti name.
203 * \par Typical use case:
204 * If user want to regist a new notification callback function with noti name, he(or she) can use this API.
206 * \par Important notes:
209 * \param fd [in] notify file descriptor created by heynoti_init()
210 * \param noti [in] notification name
211 * \param cb [in] callback function pointer
212 * \param data [in] callback function data
214 * \return Return Type (int) \n
218 * \par Prospective clients:
223 * \see heynoti_unsubscribe()
228 * #include <heynoti.h>
233 * if((fd = heynoti_init()) < 0) //Initialize heynoti
235 * fprintf(stderr, "heynoti_init fail, error_code: %d\n", fd);
236 * return; //return if unavailable file descriptor is returned
239 * if(heynoti_get_snoti_name("test_testnoti", sys_noti, sizeof(sys_noti))) //Get system noti name
241 * fprintf(stderr, "heynoti_get_snoti_name fail");
242 * heynoti_close(fd); //Finalize heynoti and return if unavailable noti name is returned
246 * if((heynoti_subscribe(fd, sys_noti, callback, NULL))< 0)
248 * fprintf(stderr, "heynoti_subscribe fail\n");
253 /*================================================================================================*/
254 int heynoti_subscribe(int fd, const char *noti, void (*cb)(void *), void *data);
258 * Unregister the notification callback function with noti name
261 * This API is used for unregistering a notification callback function with noti name.
263 * \par Typical use case:
264 * If user want to unregist a notification callback function with noti name, he(or she) can use this API.
266 * \par Important notes:
268 * \pre heynoti_init()
270 * \see heynoti_subscribe()
273 * \param fd [in] notify file descriptor created by heynoti_init()
274 * \param noti [in] notification name
275 * \param cb [in] callback function pointer
277 * \return Return Type (int) \n
281 * \par Prospective clients:
286 * #include <heynoti.h>
291 * if((fd = heynoti_init()) < 0) //Initialize heynoti
293 * fprintf(stderr, "heynoti_init fail, error_code: %d\n", fd);
294 * return; //return if unavailable file descriptor is returned
296 * if(heynoti_get_snoti_name("test_testnoti", sys_noti, sizeof(sys_noti)))
298 * fprintf(stderr, "heynoti_get_snoti_name fail");
299 * heynoti_close(fd); //Finalize heynoti and return if unavailable noti name is returned
303 * if((heynoti_subscribe(fd, sys_noti, callback, NULL))< 0)
305 * fprintf(stderr, "heynoti_subscribe fail\n");
308 * if (heynoti_unsubscribe(fd, sys_noti, callback) < 0)
310 * fprintf(stderr, "heynoti_unsubscribe fail\n");
317 /*================================================================================================*/
318 int heynoti_unsubscribe(int fd, const char *noti, void (*cb)(void *));
322 * Send a notification
325 * This API is used for sending a notification
327 * \par Typical use case:
328 * If user want to send a notification, he(or she) can use this API.
330 * \par Important notes:
333 * \param noti [in] notification name
335 * \return Return Type (int) \n
339 * \par Prospective clients:
342 * \par Related functions:
351 * #include <heynoti.h>
355 * if(heynoti_get_snoti_name("test_testnoti", sys_noti, sizeof(sys_noti)))
357 * fprintf(stderr, "heynoti_get_snoti_name fail");
360 * if(heynoti_publish(sys_noti)) //Publish with notiname
361 * fprintf(stderr, "heynoti_publish fail\n");
363 * fprintf(stderr, "heynoti_publish ok\n");
367 /*================================================================================================*/
368 int heynoti_publish(const char *noti);
372 * Wait(block) for some notification of the file descriptor
375 * This API is used for waiting(block) for some notification of the file descriptor
377 * \par Typical use case:
378 * If user want to waiting for some notification of the file descriptor, he(or she) can use this API.
380 * \par Important notes:
383 * \param fd [in] notify file descriptor created by heynoti_init()
385 * \return Return Type (int) \n
386 * - positive number - success. \n
389 * \par Prospective clients:
392 * \pre heynoti_init()
400 * #include <heynoti.h>
405 * if((fd = heynoti_init()) < 0)
407 * fprintf(stderr, "heynoti_init fail, error_code: %d\n", fd);
408 * return; //return if unavailable file descriptor is returned
411 * if(heynoti_get_snoti_name("test_testnoti", sys_noti, sizeof(sys_noti)))
413 * fprintf(stderr, "heynoti_get_snoti_name fail");
416 * if((heynoti_subscribe(fd, sys_noti, callback, NULL))< 0)
418 * fprintf(stderr, "heynoti_subscribe fail\n");
422 * if (heynoti_poll_event(fd) < 0) //Polling and waiting for event
424 * fprintf(stderr, "heynoti_poll_event() failed");
430 /*================================================================================================*/
431 int heynoti_poll_event(int fd);
435 * Activate whole heynoti callback which is added by heynoti_subscribe
436 * Attach a fd handler to the default context of g_main_loop.\n
437 * Notification is recognized by main loop
440 * This API is used for activating whole heynoti callback which is added by heynoti_subscribe.
442 * \par Typical use case:
443 * If user want to activate whole heynoti callback which is added by heynoti_subscribe, he(or she) can use this API.
445 * \par Important notes:
448 * \param fd [in] notify file descriptor created by heynoti_init()
450 * \return Return Type (int) \n
454 * \par Prospective clients:
457 * \pre heynoti_init()
459 * \see heynoti_init(), heynoti_detach_handler()
465 * #include <heynoti.h>
470 * if((fd = heynoti_init()) < 0)
472 * fprintf(stderr, "heynoti_init fail, error_code: %d\n", fd);
473 * return; //return if unavailable file descriptor is returned
476 * if(heynoti_get_snoti_name("test_testnoti", sys_noti, sizeof(sys_noti)))
478 * fprintf(stderr, "heynoti_get_snoti_name fail");
481 * if((heynoti_subscribe(fd, sys_noti, callback, NULL))< 0)
483 * fprintf(stderr, "heynoti_subscribe fail\n");
486 * if(heynoti_attach_handler(fd)) //Attach handler to main loop
488 * fprintf(stderr, "heynoti_attach_handler fail\n");
493 /*================================================================================================*/
494 int heynoti_attach_handler(int fd);
498 * Deactivate whole heynoti callback which is deleted by heynoti_unsubscribe
499 * Detach a fd handler from the default context of g_main_loop.\n
500 * Be detached the handler without calling heynoti_unsubscribe(), the event will reuse it that is attached before.
503 * This API is used for deactivating whole heynoti callback which is added by heynoti_subscribe.
505 * \par Typical use case:
506 * If user want to deactivate whole heynoti callback which is added by heynoti_subscribe, he(or she) can use this API.
508 * \par Important notes:
511 * \param fd [in] notify file descriptor created by heynoti_init()
513 * \return Return Type (int) \n
517 * \par Prospective clients:
520 * \pre heynoti_init()
522 * \see heynoti_attach_handler()
527 * #include <heynoti.h>
532 * if((fd = heynoti_init()) < 0)
534 * fprintf(stderr, "heynoti_init fail, error_code: %d\n", fd);
535 * return; //return if unavailable file descriptor is returned
538 * if(heynoti_get_snoti_name("test_testnoti", sys_noti, sizeof(sys_noti)))
540 * fprintf(stderr, "heynoti_get_snoti_name fail");
543 * if((heynoti_subscribe(fd, sys_noti, callback, NULL))< 0)
545 * fprintf(stderr, "heynoti_subscribe fail\n");
547 * if(heynoti_attach_handler(fd)) //Attach handler to main loop
549 * fprintf(stderr, "heynoti_attach_handler fail\n");
551 * if(heynoti_detach_handler(fd) < 0) //Detach handler from main loop
553 * fprintf(stderr, "heynoti_detach_handler() failed");
558 int heynoti_detach_handler(int fd);
562 * Make a name of system notification
565 * This API is used for making a name of system notification
567 * \par Typical use case:
568 * If user want to make a name of system notification, he(or she) can use this API.
570 * \par Important notes:
573 * \param name [in] notification name
574 * \param buf buffer [out] to get a system notification
575 * \param buf_size [in] The size of buffer should be "@p name + 6 or more"
577 * \return Return Type (int) \n
581 * \par Prospective clients:
591 * #include <heynoti.h>
595 * if(heynoti_get_snoti_name("test_testnoti", sys_noti, sizeof(sys_noti)))
597 * fprintf(stderr, "heynoti_get_snoti_name fail");
600 * if(heynoti_publish(sys_noti)) //Publish
601 * fprintf(stderr, "heynoti_publish fail\n");
603 * fprintf(stderr, "heynoti_publish ok\n");
607 /*================================================================================================*/
608 int heynoti_get_snoti_name(const char *name, char *buf, int buf_size);
612 * Make the name of process notification
613 * <br>buf must be allocated.
616 * This API is used for making a name of process notification
618 * \par Typical use case:
619 * If user want to make a name of process notification, he(or she) can use this API.
621 * \par Important notes:
624 * \param pid [in] process id
625 * \param name [in] notification name
626 * \param buf buffer [out] to get a name of process notification
627 * \param buf_size [in] The size of buffer should be more than the sum of characters in pid, name and extra space(3 bytes)
629 * \return Return Type (int) \n
633 * \par Prospective clients:
636 * \pre heynoti_init()
643 * #include <heynoti.h>
645 * char process_noti[25];
647 * if(heynoti_get_pnoti_name(getpid(), "test_testnoti", process_noti, sizeof(process_noti));
649 * fprintf(stderr, "heynoti_get_pnoti_name fail");
652 * if(heynoti_publish(process_noti)) //Publish
653 * fprintf(stderr, "heynoti_publish fail\n");
655 * fprintf(stderr, "heynoti_publish ok\n");
659 /*================================================================================================*/
660 int heynoti_get_pnoti_name(pid_t pid, const char *name, char *buf, int buf_size);
671 #endif /* __HEYNOTI_H__ */