diff options
author | iphydf <iphydf@users.noreply.github.com> | 2016-11-05 16:52:41 +0000 |
---|---|---|
committer | iphydf <iphydf@users.noreply.github.com> | 2016-11-06 20:35:09 +0000 |
commit | 82515f92eecde2dffc0659519317d00459a09239 (patch) | |
tree | f17b9afe68fdd475be368623d58c7f51e8cc0ba2 /toxcore/tox.h | |
parent | fcc8ad943e93308b7048c4e0071ae00b54804934 (diff) |
Move log callback to options.
Previously, all log messages generated by tox_new (which is quite a lot)
were dropped, because client code had no chance to register a logging
callback, yet. This change allows setting the log callback from the
beginning and removes the ability to unset it.
Since the log callback is forever special, since it can't be stateless,
we don't necessarily need to treat it uniformly (with `event`).
Diffstat (limited to 'toxcore/tox.h')
-rw-r--r-- | toxcore/tox.h | 134 |
1 files changed, 74 insertions, 60 deletions
diff --git a/toxcore/tox.h b/toxcore/tox.h index d97d94c7..4c5266fa 100644 --- a/toxcore/tox.h +++ b/toxcore/tox.h | |||
@@ -419,6 +419,60 @@ typedef enum TOX_SAVEDATA_TYPE { | |||
419 | 419 | ||
420 | 420 | ||
421 | /** | 421 | /** |
422 | * Severity level of log messages. | ||
423 | */ | ||
424 | typedef enum TOX_LOG_LEVEL { | ||
425 | |||
426 | /** | ||
427 | * Very detailed traces including all network activity. | ||
428 | */ | ||
429 | TOX_LOG_LEVEL_TRACE, | ||
430 | |||
431 | /** | ||
432 | * Debug messages such as which port we bind to. | ||
433 | */ | ||
434 | TOX_LOG_LEVEL_DEBUG, | ||
435 | |||
436 | /** | ||
437 | * Informational log messages such as video call status changes. | ||
438 | */ | ||
439 | TOX_LOG_LEVEL_INFO, | ||
440 | |||
441 | /** | ||
442 | * Warnings about internal inconsistency or logic errors. | ||
443 | */ | ||
444 | TOX_LOG_LEVEL_WARNING, | ||
445 | |||
446 | /** | ||
447 | * Severe unexpected errors caused by external or internal inconsistency. | ||
448 | */ | ||
449 | TOX_LOG_LEVEL_ERROR, | ||
450 | |||
451 | } TOX_LOG_LEVEL; | ||
452 | |||
453 | |||
454 | /** | ||
455 | * This event is triggered when the toxcore library logs an internal message. | ||
456 | * This is mostly useful for debugging. This callback can be called from any | ||
457 | * function, not just tox_iterate. This means the user data lifetime must at | ||
458 | * least extend between registering and unregistering it or tox_kill. | ||
459 | * | ||
460 | * Other toxcore modules such as toxav may concurrently call this callback at | ||
461 | * any time. Thus, user code must make sure it is equipped to handle concurrent | ||
462 | * execution, e.g. by employing appropriate mutex locking. | ||
463 | * | ||
464 | * @param level The severity of the log message. | ||
465 | * @param file The source file from which the message originated. | ||
466 | * @param line The source line from which the message originated. | ||
467 | * @param func The function from which the message originated. | ||
468 | * @param message The log message. | ||
469 | * @param user_data The user data pointer passed to tox_new in options. | ||
470 | */ | ||
471 | typedef void tox_log_cb(Tox *tox, TOX_LOG_LEVEL level, const char *file, uint32_t line, const char *func, | ||
472 | const char *message, void *user_data); | ||
473 | |||
474 | |||
475 | /** | ||
422 | * This struct contains all the startup options for Tox. You can either | 476 | * This struct contains all the startup options for Tox. You can either |
423 | * allocate this object yourself, and pass it to tox_options_default, or call tox_options_new to get | 477 | * allocate this object yourself, and pass it to tox_options_default, or call tox_options_new to get |
424 | * a new default options object. | 478 | * a new default options object. |
@@ -540,6 +594,18 @@ struct Tox_Options { | |||
540 | */ | 594 | */ |
541 | size_t savedata_length; | 595 | size_t savedata_length; |
542 | 596 | ||
597 | |||
598 | /** | ||
599 | * Logging callback for the new tox instance. | ||
600 | */ | ||
601 | tox_log_cb *log_callback; | ||
602 | |||
603 | |||
604 | /** | ||
605 | * User data pointer passed to the logging callback. | ||
606 | */ | ||
607 | void *log_user_data; | ||
608 | |||
543 | }; | 609 | }; |
544 | 610 | ||
545 | 611 | ||
@@ -587,6 +653,14 @@ size_t tox_options_get_savedata_length(const struct Tox_Options *options); | |||
587 | 653 | ||
588 | void tox_options_set_savedata_length(struct Tox_Options *options, size_t length); | 654 | void tox_options_set_savedata_length(struct Tox_Options *options, size_t length); |
589 | 655 | ||
656 | tox_log_cb *tox_options_get_log_callback(const struct Tox_Options *options); | ||
657 | |||
658 | void tox_options_set_log_callback(struct Tox_Options *options, tox_log_cb *callback); | ||
659 | |||
660 | void *tox_options_get_log_user_data(const struct Tox_Options *options); | ||
661 | |||
662 | void tox_options_set_log_user_data(struct Tox_Options *options, void *user_data); | ||
663 | |||
590 | /** | 664 | /** |
591 | * Initialises a Tox_Options object with the default options. | 665 | * Initialises a Tox_Options object with the default options. |
592 | * | 666 | * |
@@ -735,66 +809,6 @@ Tox *tox_new(const struct Tox_Options *options, TOX_ERR_NEW *error); | |||
735 | void tox_kill(Tox *tox); | 809 | void tox_kill(Tox *tox); |
736 | 810 | ||
737 | /** | 811 | /** |
738 | * Severity level of log messages. | ||
739 | */ | ||
740 | typedef enum TOX_LOG_LEVEL { | ||
741 | |||
742 | /** | ||
743 | * Very detailed traces including all network activity. | ||
744 | */ | ||
745 | TOX_LOG_LEVEL_TRACE, | ||
746 | |||
747 | /** | ||
748 | * Debug messages such as which port we bind to. | ||
749 | */ | ||
750 | TOX_LOG_LEVEL_DEBUG, | ||
751 | |||
752 | /** | ||
753 | * Informational log messages such as video call status changes. | ||
754 | */ | ||
755 | TOX_LOG_LEVEL_INFO, | ||
756 | |||
757 | /** | ||
758 | * Warnings about internal inconsistency or logic errors. | ||
759 | */ | ||
760 | TOX_LOG_LEVEL_WARNING, | ||
761 | |||
762 | /** | ||
763 | * Severe unexpected errors caused by external or internal inconsistency. | ||
764 | */ | ||
765 | TOX_LOG_LEVEL_ERROR, | ||
766 | |||
767 | } TOX_LOG_LEVEL; | ||
768 | |||
769 | |||
770 | /** | ||
771 | * @param level The severity of the log message. | ||
772 | * @param file The source file from which the message originated. | ||
773 | * @param line The source line from which the message originated. | ||
774 | * @param func The function from which the message originated. | ||
775 | * @param message The log message. | ||
776 | */ | ||
777 | typedef void tox_log_cb(Tox *tox, TOX_LOG_LEVEL level, const char *file, uint32_t line, const char *func, | ||
778 | const char *message, void *user_data); | ||
779 | |||
780 | |||
781 | /** | ||
782 | * Set the callback for the `log` event. Pass NULL to unset. | ||
783 | * | ||
784 | * This event is triggered when the toxcore library logs an internal message. | ||
785 | * This is mostly useful for debugging. This callback can be called from any | ||
786 | * function, not just tox_iterate. This means the user data lifetime must at | ||
787 | * least extend between registering and unregistering it or tox_kill. | ||
788 | * | ||
789 | * Other toxcore modules such as toxav may concurrently call this callback at | ||
790 | * any time. Thus, user code must make sure it is equipped to handle concurrent | ||
791 | * execution, e.g. by employing appropriate mutex locking. The callback | ||
792 | * registration function must not be called during execution of any other Tox | ||
793 | * library function (toxcore or toxav). | ||
794 | */ | ||
795 | void tox_callback_log(Tox *tox, tox_log_cb *callback, void *user_data); | ||
796 | |||
797 | /** | ||
798 | * Calculates the number of bytes required to store the tox instance with | 812 | * Calculates the number of bytes required to store the tox instance with |
799 | * tox_get_savedata. This function cannot fail. The result is always greater than 0. | 813 | * tox_get_savedata. This function cannot fail. The result is always greater than 0. |
800 | * | 814 | * |