heynoti.h

   1 /*
   2  * heynoti
   3  *
   4  * Copyright (c) 2000 - 2011 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Contact: Jayoun Lee <airjany@samsung.com>, Sewook Park <sewook7.park@samsung.com>,
   7  * Jaeho Lee <jaeho81.lee@samsung.com>
   8  *
   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
  12  *
  13  * http://www.apache.org/licenses/LICENSE-2.0
  14  *
  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.
  20  *
  21  */
  22
  23
  24
  25 #ifndef __HEYNOTI_H__
  26 #define __HEYNOTI_H__
  27
  28 /**
  29  * @addtogroup APPLICATION_FRAMEWORK
  30  * @{
  31  *
  32  * @defgroup   HEYNOTI HEY(ligHt Easy speedY) Notification
  33  * @brief      HEY(ligHt Easy speedY) Notification
  34  *
  35  * @section Header To use Them:
  36  * @code
  37  * #include <heynoti.h>
  38  * @endcode
  39  *
  40  * @section Properties
  41  * - Light, Easy and speedy notification (in other words,  HEY - ligHt Easy speedY)
  42  * - Convenient API
  43  * - Simple notification based on inotify
  44  *
  45  * @section example Simple Example
  46  * @code
  47 #include <stdio.h>
  48 #include <glib.h>
  49 #include <heynoti.h>
  50
  51 void callback(void *data)
  52 {
  53    printf("I got a testnoti\n");
  54 }
  55
  56 int main(int argc, const char *argv[])
  57 {
  58    int fd;
  59    GMainLoop *loop;
  60
  61    if((fd = heynoti_init()) < 0) {
  62       fprintf(stderr, "heynoti_init FAIL\n");
  63       return -1;
  64    }else
  65       printf("heynoti_init OK\n");
  66
  67    if(heynoti_subscribe(fd, "test_testnoti", callback, NULL))
  68       fprintf(stderr, "heynoti_subscribe FAIL\n");
  69    else
  70       printf("heynoti_subscribe OK\n");
  71
  72     if(heynoti_attach_handler(fd))
  73        fprintf(stderr, "heynoti_attach_handler FAIL\n");
  74     else
  75        printf("heynoti_attach_handler OK\n");
  76
  77    loop = g_main_loop_new(NULL, FALSE);
  78    g_main_loop_run(loop);
  79
  80    heynoti_close(fd);
  81    g_main_loop_unref(loop);
  82
  83    return 0;
  84 }
  85  * @endcode
  86  */
  87
  88 /**
  89  * @addtogroup HEYNOTI
  90  * @{
  91  */
  92
  93 #include <sys/types.h>
  94 #include <sys/inotify.h>
  95
  96 #ifdef __cplusplus
  97 extern "C" {
  98 #endif
  99
 100 /************************************************
 101  * API for Notification                         *
 102  ************************************************/
 103
 104 /**
 105  * \par Description:
 106  * Initialize the notify service\n
 107  * Get file descriptor associated with a new inotify event queue.\n
 108  *
 109  * \par Purpose:
 110  * This API is used for initializing notify service.
 111  *
 112  * \par Typical use case:
 113  * If user want to initialize notify service, he(or she) can use this API.
 114  *
 115  * \par Important notes:
 116  * None
 117  *
 118  * \return Return Type (int) \n
 119  * - fd - fild descriptor. \n
 120  * - -1 - fail to create file descriptor. \n
 121  *
 122  * \par Prospective clients:
 123  * External Apps.
 124  *
 125  * \par Related functions:
 126  * heynoti_close()
 127  *
 128  * \pre None
 129  * \post None
 130  * \see heynoti_close()
 131  * \remark      None
 132  * \par Sample code:
 133  * \code
 134  * ...
 135  * #include <heynoti.h> //Include heynoti.h file
 136  * ...
 137  *
 138  *      int fd = heynoti_init(); //Initialize heynoti
 139  *
 140  *      if (fd < 0) {
 141  *              printf("heynoti_init() failed\n");
 142  *              return;  //return if unavailable file descriptor is returned
 143  *      }
 144  *
 145  * ...
 146  * \endcode
 147  */
 148 /*================================================================================================*/
 149 int heynoti_init(void);
 150
 151 /**
 152  * \par Description:
 153  * Finalizes notification service\n
 154  * Close the file descriptor and remove handler related fd.\n
 155  *
 156  * \par Purpose:
 157  * This API is used for finalizing notify service.
 158  *
 159  * \par Typical use case:
 160  * If user want to finalize notify service, he(or she) can use this API.
 161  *
 162  * \par Important notes:
 163  * None
 164  *
 165  * \param fd    [in]    file descriptor that is created by calling heynoti_ini().
 166  *
 167  * \par Prospective clients:
 168  * External Apps.
 169  *
 170  * \par Related functions:
 171  * heynoti_init()
 172  *
 173  * \pre heynoti_init()
 174  * \post None
 175  * \see heynoti_init()
 176  * \remark      None
 177  * \par Sample code:
 178  * \code
 179  * ...
 180  * #include <heynoti.h> //Include heynoti.h file
 181  * ...
 182  *      int fd = heynoti_init(); //Initialize heynoti
 183  *
 184  *      if (fd < 0) {
 185  *              fprintf(stderr, "heynoti_init fail, error_code: %d\n", fd);
 186  *              return; //return if unavailable file descriptor is returned
 187  *      }
 188  *
 189  *      heynoti_close(fd); //Finalize heynoti
 190  * ...
 191  * \endcode
 192  */
 193 /*================================================================================================*/
 194 void heynoti_close(int fd);
 195
 196 /**
 197  * \par Description:
 198  * Register a new notification callback function with noti name\n
 199  *
 200  * \par Purpose:
 201  * This API is used for registering a new notification callback function with noti name.
 202  *
 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.
 205  *
 206  * \par Important notes:
 207  * None
 208  *
 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
 213  *
 214  * \return Return Type (int) \n
 215  * - 0  - success. \n
 216  * - -1 - fail. \n
 217  *
 218  * \par Prospective clients:
 219  * External Apps.
 220  *
 221  * \pre None
 222  * \post None
 223  * \see heynoti_unsubscribe()
 224  * \remark  None
 225  * \par Sample code:
 226  * \code
 227  * ...
 228  * #include <heynoti.h>
 229  * ...
 230  *      int fd;
 231  *      char sys_noti[20];
 232  *
 233  *      if((fd = heynoti_init()) < 0) //Initialize heynoti
 234  *      {
 235  *              fprintf(stderr, "heynoti_init fail, error_code: %d\n", fd);
 236  *              return; //return if unavailable file descriptor is returned
 237  *      }
 238  *
 239  *      if(heynoti_get_snoti_name("test_testnoti", sys_noti, sizeof(sys_noti))) //Get system noti name
 240  *      {
 241  *              fprintf(stderr, "heynoti_get_snoti_name fail");
 242  *              heynoti_close(fd);  //Finalize heynoti and return if unavailable noti name is returned
 243  *              return;
 244  *      }
 245  *
 246  *      if((heynoti_subscribe(fd, sys_noti, callback, NULL))< 0)
 247  *      {
 248  *              fprintf(stderr, "heynoti_subscribe fail\n");
 249  *      }
 250  * ...
 251  * \endcode
 252  */
 253 /*================================================================================================*/
 254 int heynoti_subscribe(int fd, const char *noti, void (*cb)(void *), void *data);
 255
 256 /**
 257  * \par Description:
 258  * Unregister the notification callback function with noti name
 259  *
 260  * \par Purpose:
 261  * This API is used for unregistering a notification callback function with noti name.
 262  *
 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.
 265  *
 266  * \par Important notes:
 267  * None
 268  * \pre heynoti_init()
 269  * \post None
 270  * \see heynoti_subscribe()
 271  * \remark  None
 272  *
 273  * \param       fd      [in]    notify file descriptor created by heynoti_init()
 274  * \param       noti    [in]    notification name
 275  * \param       cb      [in]    callback function pointer
 276  *
 277  * \return Return Type (int) \n
 278  * - 0  - success. \n
 279  * - -1 - fail. \n
 280  *
 281  * \par Prospective clients:
 282  * External Apps.
 283  * \par Sample code:
 284  * \code
 285  * ...
 286  * #include <heynoti.h>
 287  * ...
 288  *      int fd;
 289  *      char sys_noti[20];
 290  *
 291  *      if((fd = heynoti_init()) < 0) //Initialize heynoti
 292  *      {
 293  *              fprintf(stderr, "heynoti_init fail, error_code: %d\n", fd);
 294  *              return; //return if unavailable file descriptor is returned
 295  *      }
 296  *      if(heynoti_get_snoti_name("test_testnoti", sys_noti, sizeof(sys_noti)))
 297  *      {
 298  *              fprintf(stderr, "heynoti_get_snoti_name fail");
 299  *              heynoti_close(fd);  //Finalize heynoti and return if unavailable noti name is returned
 300  *              return;
 301  *      }
 302  *
 303  *      if((heynoti_subscribe(fd, sys_noti, callback, NULL))< 0)
 304  *      {
 305  *              fprintf(stderr, "heynoti_subscribe fail\n");
 306  *      }
 307  *
 308  *      if (heynoti_unsubscribe(fd, sys_noti, callback) < 0)
 309  *      {
 310  *              fprintf(stderr, "heynoti_unsubscribe fail\n");
 311  *      }
 312  *
 313  *      heynoti_close(fd);
 314  * ...
 315  * \endcode
 316  */
 317 /*================================================================================================*/
 318 int heynoti_unsubscribe(int fd, const char *noti, void (*cb)(void *));
 319
 320 /**
 321  * \par Description:
 322  * Send a notification
 323  *
 324  * \par Purpose:
 325  * This API is used for sending a notification
 326  *
 327  * \par Typical use case:
 328  * If user want to send a notification, he(or she) can use this API.
 329  *
 330  * \par Important notes:
 331  * None
 332  *
 333  * \param       noti    [in]    notification name
 334  *
 335  * \return Return Type (int) \n
 336  * - 0  - success. \n
 337  * - -1 - fail. \n
 338  *
 339  * \par Prospective clients:
 340  * External Apps.
 341  *
 342  * \par Related functions:
 343  * None
 344  * \pre None
 345  * \post None
 346  * \see None
 347  * \remark  None
 348  * \par Sample code:
 349  * \code
 350  * ...
 351  * #include <heynoti.h>
 352  * ...
 353  *      char sys_noti[20];
 354  *
 355  *      if(heynoti_get_snoti_name("test_testnoti", sys_noti, sizeof(sys_noti)))
 356  *      {
 357  *              fprintf(stderr, "heynoti_get_snoti_name fail");
 358  *      }
 359  *
 360  *      if(heynoti_publish(sys_noti)) //Publish with notiname
 361  *              fprintf(stderr, "heynoti_publish fail\n");
 362  *      else
 363  *              fprintf(stderr, "heynoti_publish ok\n");
 364  * ...
 365  * \endcode
 366  */
 367 /*================================================================================================*/
 368 int heynoti_publish(const char *noti);
 369
 370 /**
 371  * \par Description:
 372  * Wait(block) for some notification of the file descriptor
 373  *
 374  * \par Purpose:
 375  * This API is used for waiting(block) for some notification of the file descriptor
 376  *
 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.
 379  *
 380  * \par Important notes:
 381  * None
 382  *
 383  * \param       fd      [in]    notify file descriptor created by heynoti_init()
 384  *
 385  * \return Return Type (int) \n
 386  * - positive number - success. \n
 387  * - -1 - fail. \n
 388  *
 389  * \par Prospective clients:
 390  * External Apps.
 391  *
 392  * \pre heynoti_init()
 393  * \post None
 394  * \see None
 395  * \remark  None
 396  *
 397  * \par Sample code:
 398  * \code
 399  * ...
 400  * #include <heynoti.h>
 401  * ...
 402  *      int fd;
 403  *      char sys_noti[20];
 404  *
 405  *      if((fd = heynoti_init()) < 0)
 406  *      {
 407  *              fprintf(stderr, "heynoti_init fail, error_code: %d\n", fd);
 408  *              return; //return if unavailable file descriptor is returned
 409  *      }
 410  *
 411  *      if(heynoti_get_snoti_name("test_testnoti", sys_noti, sizeof(sys_noti)))
 412  *      {
 413  *              fprintf(stderr, "heynoti_get_snoti_name fail");
 414  *      }
 415  *
 416  *      if((heynoti_subscribe(fd, sys_noti, callback, NULL))< 0)
 417  *      {
 418  *              fprintf(stderr, "heynoti_subscribe fail\n");
 419  *      }
 420  * ...
 421  *
 422  *      if (heynoti_poll_event(fd) < 0) //Polling and waiting for event
 423  *      {
 424  *              fprintf(stderr, "heynoti_poll_event() failed");
 425  *      }
 426  *
 427  * ...
 428  * \endcode
 429  */
 430 /*================================================================================================*/
 431 int heynoti_poll_event(int fd);
 432
 433 /**
 434  * \par Description:
 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
 438  *
 439  * \par Purpose:
 440  * This API is used for activating whole heynoti callback which is added by heynoti_subscribe.
 441  *
 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.
 444  *
 445  * \par Important notes:
 446  * None
 447  *
 448  * \param       fd      [in]    notify file descriptor created by heynoti_init()
 449  *
 450  * \return Return Type (int) \n
 451  * - 0 - success. \n
 452  * - -1 - fail. \n
 453  *
 454  * \par Prospective clients:
 455  * External Apps.
 456  *
 457  * \pre heynoti_init()
 458  * \post None
 459  * \see heynoti_init(), heynoti_detach_handler()
 460  * \remark      None
 461  *
 462  * \par Sample code:
 463  * \code
 464  * ...
 465  * #include <heynoti.h>
 466  * ...
 467  *      int fd;
 468  *      char sys_noti[20];
 469  *
 470  *      if((fd = heynoti_init()) < 0)
 471  *      {
 472  *              fprintf(stderr, "heynoti_init fail, error_code: %d\n", fd);
 473  *              return; //return if unavailable file descriptor is returned
 474  *      }
 475  *
 476  *      if(heynoti_get_snoti_name("test_testnoti", sys_noti, sizeof(sys_noti)))
 477  *      {
 478  *              fprintf(stderr, "heynoti_get_snoti_name fail");
 479  *      }
 480  *
 481  *      if((heynoti_subscribe(fd, sys_noti, callback, NULL))< 0)
 482  *      {
 483  *              fprintf(stderr, "heynoti_subscribe fail\n");
 484  *      }
 485  *
 486  *      if(heynoti_attach_handler(fd)) //Attach handler to main loop
 487  *      {
 488  *              fprintf(stderr, "heynoti_attach_handler fail\n");
 489  *      }
 490  * ...
 491  * \endcode
 492  */
 493 /*================================================================================================*/
 494 int heynoti_attach_handler(int fd);
 495
 496 /**
 497  * \par Description:
 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.
 501  *
 502  * \par Purpose:
 503  * This API is used for deactivating whole heynoti callback which is added by heynoti_subscribe.
 504  *
 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.
 507  *
 508  * \par Important notes:
 509  * None
 510  *
 511  * \param       fd      [in]    notify file descriptor created by heynoti_init()
 512  *
 513  * \return Return Type (int) \n
 514  * - 0 - success. \n
 515  * - -1 - fail. \n
 516  *
 517  * \par Prospective clients:
 518  * External Apps.
 519  *
 520  * \pre heynoti_init()
 521  * \post None
 522  * \see heynoti_attach_handler()
 523  * \remark      None
 524  * \par Sample code:
 525  * \code
 526  * ...
 527  * #include <heynoti.h>
 528  * ...
 529  *      int fd;
 530  *      char sys_noti[20];
 531  *
 532  *      if((fd = heynoti_init()) < 0)
 533  *      {
 534  *              fprintf(stderr, "heynoti_init fail, error_code: %d\n", fd);
 535  *              return; //return if unavailable file descriptor is returned
 536  *      }
 537  *
 538  *      if(heynoti_get_snoti_name("test_testnoti", sys_noti, sizeof(sys_noti)))
 539  *      {
 540  *              fprintf(stderr, "heynoti_get_snoti_name fail");
 541  *      }
 542  *
 543  *      if((heynoti_subscribe(fd, sys_noti, callback, NULL))< 0)
 544  *      {
 545  *              fprintf(stderr, "heynoti_subscribe fail\n");
 546  *      }
 547  *      if(heynoti_attach_handler(fd)) //Attach handler to main loop
 548  *      {
 549  *              fprintf(stderr, "heynoti_attach_handler fail\n");
 550  *      }
 551  *      if(heynoti_detach_handler(fd) < 0) //Detach handler from main loop
 552  *      {
 553  *              fprintf(stderr, "heynoti_detach_handler() failed");
 554  *      }
 555  * ...
 556  * \endcode
 557  */
 558 int heynoti_detach_handler(int fd);
 559
 560 /**
 561  * \par Description:
 562  * Make a name of system notification
 563  *
 564  * \par Purpose:
 565  * This API is used for making a name of system notification
 566  *
 567  * \par Typical use case:
 568  * If user want to make a name of system notification, he(or she) can use this API.
 569  *
 570  * \par Important notes:
 571  * None
 572  *
 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"
 576  *
 577  * \return Return Type (int) \n
 578  * - 0  - success. \n
 579  * - -1 - fail. \n
 580  *
 581  * \par Prospective clients:
 582  * External Apps.
 583  *
 584  * \pre None
 585  * \post None
 586  * \see None
 587  * \remark  None
 588  * \par Sample code:
 589  * \code
 590  * ...
 591  * #include <heynoti.h>
 592  * ...
 593  *      char sys_noti[20];
 594  *
 595  *      if(heynoti_get_snoti_name("test_testnoti", sys_noti, sizeof(sys_noti)))
 596  *      {
 597  *              fprintf(stderr, "heynoti_get_snoti_name fail");
 598  *      }
 599  *
 600  *      if(heynoti_publish(sys_noti)) //Publish
 601  *              fprintf(stderr, "heynoti_publish fail\n");
 602  *      else
 603  *              fprintf(stderr, "heynoti_publish ok\n");
 604  * ...
 605  * \endcode
 606  */
 607 /*================================================================================================*/
 608 int heynoti_get_snoti_name(const char *name, char *buf, int buf_size);
 609
 610 /**
 611  * \par Description:
 612  * Make the name of process notification
 613  * <br>buf must be allocated.
 614  *
 615  * \par Purpose:
 616  * This API is used for making a name of process notification
 617  *
 618  * \par Typical use case:
 619  * If user want to make a name of process notification, he(or she) can use this API.
 620  *
 621  * \par Important notes:
 622  * None
 623  *
 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)
 628  *
 629  * \return Return Type (int) \n
 630  * - 0  - success. \n
 631  * - -1 - fail. \n
 632  *
 633  * \par Prospective clients:
 634  * External Apps.
 635  *
 636  * \pre heynoti_init()
 637  * \post None
 638  * \see None
 639  * \remark      None
 640  * \par Sample code:
 641  * \code
 642  * ...
 643  * #include <heynoti.h>
 644  * ...
 645  *      char process_noti[25];
 646  *
 647  *      if(heynoti_get_pnoti_name(getpid(), "test_testnoti", process_noti, sizeof(process_noti));
 648  *      {
 649  *              fprintf(stderr, "heynoti_get_pnoti_name fail");
 650  *      }
 651  *
 652  *      if(heynoti_publish(process_noti)) //Publish
 653  *              fprintf(stderr, "heynoti_publish fail\n");
 654  *      else
 655  *              fprintf(stderr, "heynoti_publish ok\n");
 656  * ...
 657  * \endcode
 658  */
 659 /*================================================================================================*/
 660 int heynoti_get_pnoti_name(pid_t pid, const char *name, char *buf, int buf_size);
 661
 662
 663 #ifdef __cplusplus
 664 }
 665 #endif
 666
 667 /**
 668  * @} @}
 669  */
 670
 671 #endif /* __HEYNOTI_H__ */