1 /* 2 * GPAC - Multimedia Framework C SDK 3 * 4 * Authors: Jean Le Feuvre 5 * Copyright (c) Telecom ParisTech 2000-2020 6 * All rights reserved 7 * 8 * This file is part of GPAC / common tools sub-project 9 * 10 * GPAC is free software; you can redistribute it and/or modify 11 * it under the terms of the GNU Lesser General Public License as published by 12 * the Free Software Foundation; either version 2, or (at your option) 13 * any later version. 14 * 15 * GPAC is distributed in the hope that it will be useful, 16 * but WITHOUT ANY WARRANTY; without even the implied warranty of 17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18 * GNU Lesser General Public License for more details. 19 * 20 * You should have received a copy of the GNU Lesser General Public 21 * License along with this library; see the file COPYING. If not, write to 22 * the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. 23 * 24 */ 25 26 #ifndef _GF_TOOLS_H_ 27 #define _GF_TOOLS_H_ 28 29 #ifdef __cplusplus 30 extern "C" { 31 #endif 32 33 #include <gpac/setup.h> 34 #include <gpac/version.h> 35 #include <time.h> 36 37 38 /*! 39 \file "gpac/tools.h" 40 \brief Core definitions and tools of GPAC. 41 42 This file contains basic functions and core definitions of the GPAC framework. This file is 43 usually included by all GPAC header files since it contains the error definitions. 44 */ 45 46 /*! 47 \addtogroup utils_grp Core Tools 48 \brief Core definitions and tools of GPAC. 49 50 You will find in this module the documentation of the core tools used in GPAC. 51 */ 52 53 /*! 54 \addtogroup setup_grp 55 @{ 56 */ 57 58 /*! 59 \brief Stringizer 60 \hideinitializer 61 62 Macro transforming its input name into a string 63 */ 64 #define gf_stringizer(x) #x 65 66 /*! 67 \brief 4CC Formatting 68 \hideinitializer 69 70 Macro formating a 4-character code (or 4CC) "abcd" as 0xAABBCCDD 71 */ 72 #ifndef GF_4CC 73 #define GF_4CC(a,b,c,d) ((((u32)a)<<24)|(((u32)b)<<16)|(((u32)c)<<8)|((u32)d)) 74 #endif 75 76 /*! minimum buffer size to hold any 4CC in string format*/ 77 #define GF_4CC_MSIZE 10 78 79 /*! converts four character code to string 80 \param type a four character code 81 \return a printable form of the code 82 */ 83 const char *gf_4cc_to_str(u32 type); 84 85 /*! @} */ 86 87 /*! 88 \addtogroup errors_grp 89 \brief Error Types 90 91 This section documents all error codes used in the GPAC framework. Most of the GPAC's functions will use these as 92 return values, and some of these errors are also used for state communication with the different modules of the framework. 93 94 @{ 95 */ 96 97 /*! GPAC Error 98 \hideinitializer 99 100 Positive values are warning and info, 0 means no error and negative values are errors 101 */ 102 typedef enum 103 { 104 /*!Message from any scripting engine used in the presentation (ECMAScript, MPEG-J, ...) (Info).*/ 105 GF_SCRIPT_INFO = 3, 106 /*!Indicates a send packet is not dispatched due to pending connections.*/ 107 GF_PENDING_PACKET = 2, 108 /*!Indicates the end of a stream or of a file (Info).*/ 109 GF_EOS = 1, 110 /*! 111 \n\n 112 */ 113 /*!Operation success (no error).*/ 114 GF_OK = 0, 115 /*!\n*/ 116 /*!One of the input parameter is not correct or cannot be used in the current operating mode of the framework.*/ 117 GF_BAD_PARAM = -1, 118 /*! Memory allocation failure.*/ 119 GF_OUT_OF_MEM = -2, 120 /*! Input/Output failure (disk access, system call failures)*/ 121 GF_IO_ERR = -3, 122 /*! The desired feature or operation is not supported by the framework*/ 123 GF_NOT_SUPPORTED = -4, 124 /*! Input data has been corrupted*/ 125 GF_CORRUPTED_DATA = -5, 126 /*! A modification was attempted on a scene node which could not be found*/ 127 GF_SG_UNKNOWN_NODE = -6, 128 /*! The PROTO node interface does not match the nodes using it*/ 129 GF_SG_INVALID_PROTO = -7, 130 /*! An error occured in the scripting engine*/ 131 GF_SCRIPT_ERROR = -8, 132 /*! Buffer is too small to contain decoded data. Decoders shall use this error whenever they need to resize their output memory buffers*/ 133 GF_BUFFER_TOO_SMALL = -9, 134 /*! Bitstream is not compliant to the specfication it refers to*/ 135 GF_NON_COMPLIANT_BITSTREAM = -10, 136 /*! No filter could be found to handle the desired media type*/ 137 GF_FILTER_NOT_FOUND = -11, 138 /*! The URL is not properly formatted or cannot be found*/ 139 GF_URL_ERROR = -12, 140 /*! An service error has occured at the local side*/ 141 GF_SERVICE_ERROR = -13, 142 /*! A service error has occured at the remote (server) side*/ 143 GF_REMOTE_SERVICE_ERROR = -14, 144 /*! The desired stream could not be found in the service*/ 145 GF_STREAM_NOT_FOUND = -15, 146 /*! The IsoMedia file is not a valid one*/ 147 GF_ISOM_INVALID_FILE = -20, 148 /*! The IsoMedia file is not complete. Either the file is being downloaded, or it has been truncated*/ 149 GF_ISOM_INCOMPLETE_FILE = -21, 150 /*! The media in this IsoMedia track is not valid (usually due to a broken stream description)*/ 151 GF_ISOM_INVALID_MEDIA = -22, 152 /*! The requested operation cannot happen in the current opening mode of the IsoMedia file*/ 153 GF_ISOM_INVALID_MODE = -23, 154 /*! This IsoMedia track refers to media outside the file in an unknown way*/ 155 GF_ISOM_UNKNOWN_DATA_REF = -24, 156 157 /*! An invalid MPEG-4 Object Descriptor was found*/ 158 GF_ODF_INVALID_DESCRIPTOR = -30, 159 /*! An MPEG-4 Object Descriptor was found or added to a forbidden descriptor*/ 160 GF_ODF_FORBIDDEN_DESCRIPTOR = -31, 161 /*! An invalid MPEG-4 BIFS command was detected*/ 162 GF_ODF_INVALID_COMMAND = -32, 163 /*! The scene has been encoded using an unknown BIFS version*/ 164 GF_BIFS_UNKNOWN_VERSION = -33, 165 166 /*! The remote IP address could not be solved*/ 167 GF_IP_ADDRESS_NOT_FOUND = -40, 168 /*! The connection to the remote peer has failed*/ 169 GF_IP_CONNECTION_FAILURE = -41, 170 /*! The network operation has failed*/ 171 GF_IP_NETWORK_FAILURE = -42, 172 /*! The network connection has been closed*/ 173 GF_IP_CONNECTION_CLOSED = -43, 174 /*! The network operation has failed because no data is available*/ 175 GF_IP_NETWORK_EMPTY = -44, 176 /*! The network operation has been discarded because it would be a blocking one*/ 177 GF_IP_SOCK_WOULD_BLOCK = -45, 178 /*! UDP connection did not receive any data at all. Signaled by client services to reconfigure network if possible*/ 179 GF_IP_UDP_TIMEOUT = -46, 180 181 /*! Authentication with the remote host has failed*/ 182 GF_AUTHENTICATION_FAILURE = -50, 183 /*! Script not ready for playback */ 184 GF_SCRIPT_NOT_READY = -51, 185 /*! Bad configuration for the current context */ 186 GF_INVALID_CONFIGURATION = -52, 187 /*! The element has not been found */ 188 GF_NOT_FOUND = -53, 189 /*! Unexpected format of data */ 190 GF_PROFILE_NOT_SUPPORTED = -54, 191 /*! filter PID config requires new instance of filter */ 192 GF_REQUIRES_NEW_INSTANCE = -56, 193 /*! filter PID config cannot be supported by this filter, no use trying to find an alternate input filter chain*/ 194 GF_FILTER_NOT_SUPPORTED = -57 195 } GF_Err; 196 197 /*! 198 \brief Error Printing 199 200 Returns a printable version of a given error 201 \param e Error code requested 202 \return String representing the error 203 */ 204 const char *gf_error_to_string(GF_Err e); 205 206 /*! @} */ 207 208 209 /*! 210 \addtogroup mem_grp 211 @{ 212 */ 213 214 /*! 215 \brief Memory allocation for a structure 216 \hideinitializer 217 218 Macro allocating memory and zero-ing it 219 */ 220 #define GF_SAFEALLOC(__ptr, __struct) {\ 221 __ptr = (__struct *) gf_malloc(sizeof(__struct));\ 222 if (__ptr) {\ 223 memset((void *) __ptr, 0, sizeof(__struct));\ 224 }\ 225 } 226 227 /*! 228 \brief Memory allocation for an array of n structs 229 \hideinitializer 230 231 Macro allocating memory for n structures and zero-ing it 232 */ 233 #define GF_SAFE_ALLOC_N(__ptr, __n, __struct) {\ 234 __ptr = (__struct *) gf_malloc( __n * sizeof(__struct));\ 235 if (__ptr) {\ 236 memset((void *) __ptr, 0, __n * sizeof(__struct));\ 237 }\ 238 } 239 240 241 /*! 242 \brief dynamic string concatenation 243 244 Dynamic concatenation of string with optional separator 245 \param str pointer to destination string pointer 246 \param to_append string to append 247 \param sep optional separator string to insert before concatenation. If set and initial string is NULL, will not be appended 248 \return error code 249 */ 250 GF_Err gf_dynstrcat(char **str, const char *to_append, const char *sep); 251 252 /*! @} */ 253 254 /*! 255 \addtogroup libsys_grp 256 \brief Library configuration 257 258 These functions are used to initialize, shutdown and configure libgpac. 259 260 The library shall be initialized using \ref gf_sys_init and terminated using gf_sys_close 261 262 The library can usually be configured from command line if your program uses \ref gf_sys_set_args. 263 264 The library can also be configured from your program using \ref gf_opts_set_key and related functions right after initializing the library. 265 266 For more information on configuration options, see \code gpac -hx core \endcode and https://wiki.gpac.io/core_options 267 268 For more information on filters configuration options, see https://wiki.gpac.io/Filters 269 270 @{ 271 */ 272 273 /*! 274 Selection flags for memory tracker 275 \hideinitializer 276 */ 277 typedef enum 278 { 279 /*! No memory tracking*/ 280 GF_MemTrackerNone = 0, 281 /*! Memory tracking without backtrace*/ 282 GF_MemTrackerSimple, 283 /*! Memory tracking with backtrace*/ 284 GF_MemTrackerBackTrace, 285 } GF_MemTrackerType; 286 287 /*! 288 \brief System setup 289 290 Inits the system high-resolution clock if any, CPU usage manager, random number and GPAC global config. It is strongly recommended to call this function before calling any other GPAC functions, since on some systems (like winCE) it may result in a better memory usage estimation. 291 292 The profile allows using a different global config file than the default, and may be a name (without / or \\) or point to an existing config file. 293 \note This can be called several times but only the first call will result in system setup. 294 \param mem_tracker_type memory tracking mode 295 \param profile name of the profile to load, NULL for default. 296 \return Error code if any 297 */ 298 GF_Err gf_sys_init(GF_MemTrackerType mem_tracker_type, const char *profile); 299 /*! 300 \brief System closing 301 Closes the system high-resolution clock and any CPU associated ressources. 302 \note This can be called several times but the system will be closed when no more users are counted. 303 */ 304 void gf_sys_close(); 305 306 /*! 307 \brief System arguments 308 309 Sets the user app arguments (used by GUI mode) 310 \param argc Number of arguments 311 \param argv Array of arguments 312 \return error code if any, GF_OK otherwise 313 */ 314 GF_Err gf_sys_set_args(s32 argc, const char **argv); 315 316 /*! 317 \brief Get number of args 318 319 Gets the number of argument of the user application if any 320 \return number of argument of the user application 321 */ 322 u32 gf_sys_get_argc(); 323 324 /*! 325 \brief Get program arguments 326 327 Gets the arguments of the user application if any 328 \return argument of the user application 329 */ 330 const char **gf_sys_get_argv(); 331 332 /*! 333 \brief Get number of args 334 335 Gets the number of argument of the user application if any 336 \param arg Index of argument to retrieve 337 \return number of argument of the user application 338 */ 339 const char *gf_sys_get_arg(u32 arg); 340 341 342 /*! 343 \brief Mark arg as used 344 345 Marks the argument at given index as used. By default all args are marked as not used when assigning args 346 \param arg_idx Index of argument to mark 347 \param used flag to set 348 */ 349 void gf_sys_mark_arg_used(s32 arg_idx, Bool used); 350 351 /*! 352 \brief Check if arg is marked as used 353 354 Marks the argument at given index as used 355 \param arg_idx Index of argument to mark 356 \return used flag of the arg 357 */ 358 Bool gf_sys_is_arg_used(s32 arg_idx); 359 360 /*! 361 \brief checks if test mode is enabled 362 363 Checks if test mode is enabled (no date nor GPAC version should be written). 364 \return GF_TRUE if test mode is enabled, GF_FALSE otherwise. 365 */ 366 Bool gf_sys_is_test_mode(); 367 368 /*! 369 \brief checks if compatibility with old arch is enabled 370 371 Checks if compatibility with old arch is enabled - this function will be removed when master will be moved to filters branch 372 \return GF_TRUE if old arch compat is enabled, GF_FALSE otherwise. 373 */ 374 Bool gf_sys_old_arch_compat(); 375 376 #ifdef GPAC_ENABLE_COVERAGE 377 /*! 378 \brief checks if coverage tests are enabled 379 380 Checks if coverage tests are enabled 381 \return GF_TRUE if coverage is enabled, GF_FALSE otherwise. 382 */ 383 Bool gf_sys_is_cov_mode(); 384 #endif 385 386 /*! 387 \brief checks if running in quiet mode 388 389 Checks if quiet mode is enabled 390 \return 2 if quiet mode is enabled, 1 if quiet mode not enabled but progress is disabled, 0 otherwise. 391 */ 392 u32 gf_sys_is_quiet(); 393 394 /*! gets GPAC feature list in this GPAC build 395 \param disabled if GF_TRUE, gets disabled features, otherwise gets enabled features 396 \return the list of features. 397 */ 398 const char *gf_sys_features(Bool disabled); 399 400 /*! callback function for remotery profiler 401 \param udta user data passed by \ref gf_sys_set_profiler_callback 402 \param text string sent by webbrowser client 403 */ 404 typedef void (*gf_rmt_user_callback)(void *udta, const char* text); 405 406 /*! Enables remotery profiler callback. If remotery is enabled, commands sent via webbrowser client will be forwarded to the callback function specified 407 \param udta user data 408 \param rmt_usr_cbk callback function 409 \return GF_OK if success, GF_BAD_PARAM if profiler is not running, GF_NOT_SUPPORTED if profiler not supported 410 */ 411 GF_Err gf_sys_profiler_set_callback(void *udta, gf_rmt_user_callback rmt_usr_cbk); 412 413 414 /*! Sends a message to remotery web client 415 \param msg text message to send. The message format should be json 416 \return GF_OK if success, GF_BAD_PARAM if profiler is not running, GF_NOT_SUPPORTED if profiler not supported 417 */ 418 GF_Err gf_sys_profiler_send(const char *msg); 419 420 /*! 421 GPAC Log tools 422 \hideinitializer 423 424 Describes the color code for console print 425 */ 426 typedef enum 427 { 428 /*!reset color*/ 429 GF_CONSOLE_RESET=0, 430 /*!set text to red*/ 431 GF_CONSOLE_RED, 432 /*!set text to green*/ 433 GF_CONSOLE_GREEN, 434 /*!set text to blue*/ 435 GF_CONSOLE_BLUE, 436 /*!set text to yellow*/ 437 GF_CONSOLE_YELLOW, 438 /*!set text to cyan*/ 439 GF_CONSOLE_CYAN, 440 /*!set text to white*/ 441 GF_CONSOLE_WHITE, 442 /*!set text to magenta*/ 443 GF_CONSOLE_MAGENTA, 444 /*!reset all console text*/ 445 GF_CONSOLE_CLEAR, 446 /*!save console state*/ 447 GF_CONSOLE_SAVE, 448 /*!restore console state*/ 449 GF_CONSOLE_RESTORE, 450 451 /*!set text to bold modifier*/ 452 GF_CONSOLE_BOLD = 1<<16, 453 /*!set text to italic*/ 454 GF_CONSOLE_ITALIC = 1<<17, 455 /*!set text to underlined*/ 456 GF_CONSOLE_UNDERLINED = 1<<18, 457 /*!set text to strikethrough*/ 458 GF_CONSOLE_STRIKE = 1<<19 459 } GF_ConsoleCodes; 460 461 /*! sets console code 462 \param std the output stream (stderr or stdout) 463 \param code the console code to set 464 */ 465 void gf_sys_set_console_code(FILE *std, GF_ConsoleCodes code); 466 467 468 /*! @} */ 469 470 471 /*! 472 \addtogroup log_grp 473 \brief Logging System 474 475 @{ 476 */ 477 478 /*! 479 \brief GPAC Log Levels 480 \hideinitializer 481 482 These levels describes messages priority used when filtering logs 483 */ 484 typedef enum 485 { 486 /*! Disable all Log message*/ 487 GF_LOG_QUIET = 0, 488 /*! Log message describes an error*/ 489 GF_LOG_ERROR, 490 /*! Log message describes a warning*/ 491 GF_LOG_WARNING, 492 /*! Log message is informational (state, etc..)*/ 493 GF_LOG_INFO, 494 /*! Log message is a debug info*/ 495 GF_LOG_DEBUG 496 } GF_LOG_Level; 497 498 /*! 499 \brief Log exits at first error assignment 500 501 When GF_LOG_ERROR happens, program leaves with instruction exit(1); 502 \param strict strict behaviour when encoutering a serious error. 503 \return old value before the call. 504 */ 505 Bool gf_log_set_strict_error(Bool strict); 506 507 /*! 508 \brief gets string-formated log tools 509 510 Gets the string-formatted log tools and levels. Returned string shall be freed by the caller. 511 \return string-formatted log tools. 512 */ 513 char *gf_log_get_tools_levels(void); 514 515 /*! 516 \brief GPAC Log tools 517 \hideinitializer 518 519 These flags describes which sub-part of GPAC generates the log and are used when filtering logs 520 */ 521 typedef enum 522 { 523 /*! Log message from the core library (init, threads, network calls, etc)*/ 524 GF_LOG_CORE = 0, 525 /*! Log message from a raw media parser (BIFS, LASeR, A/V formats)*/ 526 GF_LOG_CODING, 527 /*! Log message from a bitstream parser (IsoMedia, MPEG-2 TS, OGG, ...)*/ 528 GF_LOG_CONTAINER, 529 /*! Log message from the network/service stack (messages & co)*/ 530 GF_LOG_NETWORK, 531 /*! Log message from the HTTP stack*/ 532 GF_LOG_HTTP, 533 /*! Log message from the RTP/RTCP stack (TS info) and packet structure & hinting (debug)*/ 534 GF_LOG_RTP, 535 /*! Log message from authoring subsystem (file manip, import/export)*/ 536 GF_LOG_AUTHOR, 537 /*! Log message from the sync layer of the terminal*/ 538 GF_LOG_SYNC, 539 /*! Log message from a codec*/ 540 GF_LOG_CODEC, 541 /*! Log message from any XML parser (context loading, etc)*/ 542 GF_LOG_PARSER, 543 /*! Log message from the terminal/compositor, indicating media object state*/ 544 GF_LOG_MEDIA, 545 /*! Log message from the scene graph/scene manager (handling of nodes and attribute modif, DOM core)*/ 546 GF_LOG_SCENE, 547 /*! Log message from the scripting engine APIs - does not cover alert() in the script code itself*/ 548 GF_LOG_SCRIPT, 549 /*! Log message from event handling*/ 550 GF_LOG_INTERACT, 551 /*! Log message from compositor*/ 552 GF_LOG_COMPOSE, 553 /*! Log for video object cache */ 554 GF_LOG_CACHE, 555 /*! Log message from multimedia I/O devices (audio/video input/output, ...)*/ 556 GF_LOG_MMIO, 557 /*! Log for runtime info (times, memory, CPU usage)*/ 558 GF_LOG_RTI, 559 /*! Log for SMIL timing and animation*/ 560 GF_LOG_SMIL, 561 /*! Log for memory tracker*/ 562 GF_LOG_MEMORY, 563 /*! Log for audio compositor*/ 564 GF_LOG_AUDIO, 565 /*! Generic Log for modules*/ 566 GF_LOG_MODULE, 567 /*! Log for threads and mutexes */ 568 GF_LOG_MUTEX, 569 /*! Log for threads and condition */ 570 GF_LOG_CONDITION, 571 /*! Log for all HTTP streaming */ 572 GF_LOG_DASH, 573 /*! Log for all messages coming from filters */ 574 GF_LOG_FILTER, 575 /*! Log for filter scheduler only */ 576 GF_LOG_SCHEDULER, 577 /*! Log for all ATSC3 message */ 578 GF_LOG_ATSC, 579 /*! Log for all messages coming from GF_Terminal or script alert()*/ 580 GF_LOG_CONSOLE, 581 /*! Log for all messages coming the application, not used by libgpac or the modules*/ 582 GF_LOG_APP, 583 584 /*! special value used to set a level for all tools*/ 585 GF_LOG_ALL, 586 GF_LOG_TOOL_MAX = GF_LOG_ALL, 587 } GF_LOG_Tool; 588 589 /*! 590 \brief Log modules assignment 591 592 Sets the tools to be checked for log filtering. By default no logging is performed. 593 \param log_tool the tool to be logged 594 \param log_level the level of logging for this tool 595 * 596 */ 597 void gf_log_set_tool_level(GF_LOG_Tool log_tool, GF_LOG_Level log_level); 598 599 /*! 600 \brief Log Message Callback 601 602 The gf_log_cbk type is the type for the callback of the \ref gf_log_set_callback function. By default all logs are redirected to stderr 603 \param cbck Opaque user data. 604 \param log_level level of the log. This value is not guaranteed in multi-threaded context. 605 \param log_tool tool emitting the log. This value is not guaranteed in multi-threaded context. 606 \param fmt message log format. 607 \param vlist message log param. 608 * 609 */ 610 typedef void (*gf_log_cbk)(void *cbck, GF_LOG_Level log_level, GF_LOG_Tool log_tool, const char* fmt, va_list vlist); 611 612 /*! 613 \brief Log overwrite 614 615 Assigns a user-defined callback for printing log messages. By default all logs are redirected to stderr 616 \param usr_cbk Opaque user data 617 \param cbk Callback log function 618 \return previous callback function 619 */ 620 gf_log_cbk gf_log_set_callback(void *usr_cbk, gf_log_cbk cbk); 621 622 623 /*! 624 \cond DUMMY_DOXY_SECTION 625 */ 626 #ifndef GPAC_DISABLE_LOG 627 /*note: 628 to turn log on, change to GPAC_ENABLE_LOG 629 to turn log off, change to GPAC_DISABLE_LOG 630 this is needed by configure+sed to modify this file directly 631 */ 632 #define GPAC_ENABLE_LOG 633 #endif 634 635 /*! 636 \endcond 637 */ 638 639 640 /*! \cond PRIVATE */ 641 void gf_log(const char *fmt, ...); 642 void gf_log_lt(GF_LOG_Level ll, GF_LOG_Tool lt); 643 void gf_log_va_list(GF_LOG_Level level, GF_LOG_Tool tool, const char *fmt, va_list vl); 644 /*! \endcond */ 645 646 /*! 647 \brief Log level checking 648 649 Checks if a given tool is logged for the given level 650 \param log_tool tool to check 651 \param log_level level to check 652 \return 1 if logged, 0 otherwise 653 */ 654 Bool gf_log_tool_level_on(GF_LOG_Tool log_tool, GF_LOG_Level log_level); 655 656 /*! 657 \brief Log level getter 658 659 Gets log level of a given tool 660 \param log_tool tool to check 661 \return log level of tool 662 */ 663 u32 gf_log_get_tool_level(GF_LOG_Tool log_tool); 664 665 /*! 666 \brief Set log tools and levels 667 668 Set log tools and levels according to the log_tools_levels string. 669 \param log_tools_levels string specifying the tools and levels. It is formatted as logToolX\@logLevelX:logToolZ\@logLevelZ:... 670 \param reset_all if GF_TRUE, all previous log settings are discarded. 671 \return GF_OK or GF_BAD_PARAM 672 */ 673 GF_Err gf_log_set_tools_levels(const char *log_tools_levels, Bool reset_all); 674 675 /*! 676 \brief Modify log tools and levels 677 678 Modify log tools and levels according to the log_tools_levels string. Previous log settings are kept. 679 \param val string specifying the tools and levels. It is formatted as logToolX\@logLevelX:logToolZ\@logLevelZ:... 680 \return GF_OK or GF_BAD_PARAM 681 */ 682 GF_Err gf_log_modify_tools_levels(const char *val); 683 684 /*! 685 \brief Checks if color logs is enabled 686 687 Checks if color logs is enabled 688 \return GF_TRUE if color logs are used 689 */ 690 Bool gf_log_use_color(); 691 692 /*! 693 \brief Checks if logs are stored to file 694 695 Checks if logs are stored to file 696 \return GF_TRUE if logs are stored to file 697 */ 698 Bool gf_log_use_file(); 699 700 #ifdef GPAC_DISABLE_LOG 701 #define GF_LOG(_ll, _lm, __args) 702 #else 703 /*! 704 \brief Message logging 705 \hideinitializer 706 707 Macro for logging messages. Usage is GF_LOG(log_lev, log_module, (fmt, ...)). The log function is only called if log filtering allows it. This avoids fetching logged parameters when the tool is not being logged. 708 */ 709 #define GF_LOG(_log_level, _log_tools, __args) if (gf_log_tool_level_on(_log_tools, _log_level) ) { gf_log_lt(_log_level, _log_tools); gf_log __args ;} 710 #endif 711 712 /*! 713 \brief Resets log file 714 Resets log file if any log file name was specified, by closing and reopening a new file. 715 */ 716 void gf_log_reset_file(); 717 718 719 720 /*! @} */ 721 722 /*! 723 \addtogroup miscsys_grp 724 \brief System time CPU 725 726 This section documents time functionalities and CPU management in GPAC. 727 728 @{ 729 */ 730 731 732 /*! 733 \brief PseudoRandom Integer Generation Initialization 734 735 Sets the starting point for generating a series of pseudorandom integers. 736 \param Reset Re-initializes the random number generator 737 */ 738 void gf_rand_init(Bool Reset); 739 /*! PseudoRandom integer generation 740 \return a pseudorandom integer 741 */ 742 u32 gf_rand(); 743 744 /*! gets user name 745 \param buf buffer set to current user (login) name if available. 746 */ 747 void gf_get_user_name(char buf[1024]); 748 749 /*! 750 \brief Progress formatting 751 752 Signals progress in GPAC's operations. Note that progress signaling with this function is not thread-safe, the main purpose is to use it for authoring tools only. 753 \param title title string of the progress, or NULL for no progress 754 \param done Current amount performed of the action. 755 \param total Total amount of the action. 756 */ 757 void gf_set_progress(const char *title, u64 done, u64 total); 758 759 /*! 760 \brief Progress Callback 761 762 The gf_on_progress_cbk type is the type for the callback of the \ref gf_set_progress_callback function 763 \param cbck Opaque user data. 764 \param title preogress title. 765 \param done Current amount performed of the action 766 \param total Total amount of the action. 767 * 768 */ 769 typedef void (*gf_on_progress_cbk)(const void *cbck, const char *title, u64 done, u64 total); 770 771 /*! 772 \brief Progress overwriting 773 Overwrites the progress signaling function by a user-defined one. 774 \param user_cbk Opaque user data 775 \param prog_cbk new callback function to use. Passing NULL restore default GPAC stderr notification. 776 */ 777 void gf_set_progress_callback(void *user_cbk, gf_on_progress_cbk prog_cbk); 778 779 780 /*! 781 \brief Prompt checking 782 783 Checks if a character is pending in the prompt buffer. 784 \return 1 if a character is ready to be fetched, 0 otherwise. 785 \note Function not available under WindowsCE nor SymbianOS 786 */ 787 Bool gf_prompt_has_input(); 788 789 /*! 790 \brief Prompt character flush 791 792 Gets the current character entered at prompt if any. 793 \return value of the character. 794 \note Function not available under WindowsCE nor SymbianOS 795 */ 796 char gf_prompt_get_char(); 797 798 799 /*! 800 \brief turns prompt echo on/off 801 802 Turns the prompt character echo on/off - this is useful when entering passwords. 803 \param echo_off indicates whether echo should be turned on or off. 804 \note Function not available under WindowsCE nor SymbianOS 805 */ 806 void gf_prompt_set_echo_off(Bool echo_off); 807 808 /*! @} */ 809 810 811 /*! gets battery state 812 \param onBattery set to GF_TRUE if running on battery 813 \param onCharge set to GF_TRUE if battery is charging 814 \param level set to battery charge percent 815 \param batteryLifeTime set to battery lifetime 816 \param batteryFullLifeTime set to battery full lifetime 817 \return GF_TRUE if success 818 */ 819 Bool gf_sys_get_battery_state(Bool *onBattery, u32 *onCharge, u32 *level, u32 *batteryLifeTime, u32 *batteryFullLifeTime); 820 821 822 /*! 823 \brief parses 128 bit from string 824 825 Parses 128 bit from string 826 \param string the string containing the value in hexa. Non alphanum characters are skipped 827 \param value the value parsed 828 \return error code if any 829 */ 830 GF_Err gf_bin128_parse(const char *string, bin128 value); 831 832 /*! 833 * Blob structure used to pass data pointer around 834 */ 835 typedef struct 836 { 837 /*! data block of blob */ 838 u8 *data; 839 /*! size of blob */ 840 u32 size; 841 } GF_Blob; 842 843 /*! 844 * Retrieves data associated with a blob url 845 \param blob_url URL of blob object (ie gmem://%p) 846 \param out_data if success, set to blob data pointer 847 \param out_size if success, set to blob data size 848 \return error code 849 */ 850 GF_Err gf_blob_get_data(const char *blob_url, u8 **out_data, u32 *out_size); 851 852 /*! 853 \addtogroup time_grp 854 \brief Time manipulation tools 855 @{ 856 */ 857 858 /*! 859 \brief System clock query 860 861 Gets the system clock time. 862 \return System clock value since GPAC initialization in milliseconds. 863 */ 864 u32 gf_sys_clock(); 865 866 /*! 867 \brief High precision system clock query 868 869 Gets the hight precision system clock time. 870 \return System clock value since GPAC initialization in microseconds. 871 */ 872 u64 gf_sys_clock_high_res(); 873 874 /*! 875 \brief Sleeps thread/process 876 877 Locks calling thread/process execution for a given time. 878 \param ms Amount of time to sleep in milliseconds. 879 */ 880 void gf_sleep(u32 ms); 881 882 #ifdef WIN32 883 /*! 884 \brief WINCE time constant 885 \hideinitializer 886 887 time between jan 1, 1601 and jan 1, 1970 in units of 100 nanoseconds 888 */ 889 #define TIMESPEC_TO_FILETIME_OFFSET (((LONGLONG)27111902 << 32) + (LONGLONG)3577643008) 890 891 #endif 892 893 /*! 894 \brief gets UTC time in milliseconds 895 896 Gets UTC clock in milliseconds 897 \return UTC time in milliseconds 898 */ 899 u64 gf_net_get_utc(); 900 901 /*! 902 \brief parses date 903 904 Parses date and gets UTC value for this date. Date format is an XSD dateTime format or any of the supported formats from HTTP 1.1: 905 Sun, 06 Nov 1994 08:49:37 GMT ; RFC 822, updated by RFC 1123 906 Sunday, 06-Nov-94 08:49:37 GMT ; RFC 850, obsoleted by RFC 1036 907 Sun Nov 6 08:49:37 1994 ; ANSI C's asctime() formatgets UTC time in milliseconds 908 909 \param date string containing the date to parse 910 \return UTC time in milliseconds 911 */ 912 u64 gf_net_parse_date(const char *date); 913 914 /*! 915 \brief returns 64-bit UTC timestamp from year, month, day, hour, min and sec 916 \param year the year 917 \param month the month 918 \param day the day 919 \param hour the hour 920 \param min the min 921 \param sec the sec 922 \return UTC time in milliseconds 923 */ 924 u64 gf_net_get_utc_ts(u32 year, u32 month, u32 day, u32 hour, u32 min, u32 sec); 925 926 /*! 927 \brief gets timezone adjustment in seconds 928 929 Gets timezone adjustment in seconds, with localtime - timezone = UTC time 930 \return timezone shift in seconds 931 */ 932 s32 gf_net_get_timezone(); 933 934 /*! 935 \brief gets time from UTC timestamp 936 937 Gets time from UTC timestamp 938 \param time timestamp value - see gmtime 939 \return time description structure - see gmtime 940 */ 941 struct tm *gf_gmtime(const time_t *time); 942 943 /*! @} */ 944 945 /*! 946 \addtogroup thr_grp 947 \brief Time manipulation tools 948 @{ 949 */ 950 951 /*! 952 \brief Gets process ID 953 954 Gets ID of the process running this gpac instance. 955 \return the ID of the main process 956 */ 957 u32 gf_sys_get_process_id(); 958 959 /*!\brief run-time system info object 960 961 The Run-Time Info object is used to get CPU and memory occupation of the calling process. 962 All time values are expressed in milliseconds (accuracy is not guaranteed). 963 */ 964 typedef struct 965 { 966 /*!start of the sampling period*/ 967 u32 sampling_instant; 968 /*!duration of the sampling period*/ 969 u32 sampling_period_duration; 970 /*!total amount of time (User+kernel) spent in CPU for all processes as evaluated at the end of the sampling period*/ 971 u32 total_cpu_time; 972 /*!total amount of time (User+kernel) spent in CPU for the calling process as evaluated at the end of the sampling period*/ 973 u32 process_cpu_time; 974 /*!amount of time (User+kernel) spent in CPU for all processes during the sampling period*/ 975 u32 total_cpu_time_diff; 976 /*!total amount of time (User+kernel) spent in CPU for the calling process during the sampling period*/ 977 u32 process_cpu_time_diff; 978 /*!total amount of idle time during the sampling period.*/ 979 u32 cpu_idle_time; 980 /*!percentage (from 0 to 100) of CPU usage during the sampling period.*/ 981 u32 total_cpu_usage; 982 /*!percentage (from 0 to 100) of the CPU usage by the calling process during the sampling period.*/ 983 u32 process_cpu_usage; 984 /*!calling process ID*/ 985 u32 pid; 986 /*!calling process thread count if known*/ 987 u32 thread_count; 988 /*!size of calling process allocated heaps*/ 989 u64 process_memory; 990 /*!total physical memory in system*/ 991 u64 physical_memory; 992 /*!available physical memory in system*/ 993 u64 physical_memory_avail; 994 /*!total memory currently allocated by gpac*/ 995 u64 gpac_memory; 996 /*!total number of cores on the system*/ 997 u32 nb_cores; 998 } GF_SystemRTInfo; 999 1000 /*! 1001 Selection flags for run-time info retrieval 1002 \hideinitializer 1003 */ 1004 enum 1005 { 1006 /*!Indicates all processes' times must be fetched. If not set, only the current process times will be retrieved, and the 1007 thread count and total times won't be available*/ 1008 GF_RTI_ALL_PROCESSES_TIMES = 1, 1009 /*!Indicates the process allocated heap size must be fetch. If not set, only the system physical memory is fetched. 1010 Fetching the entire ocess allocated memory can have a large impact on performances*/ 1011 GF_RTI_PROCESS_MEMORY = 1<<1, 1012 /*!Indicates that only system memory should be fetched. When set, all refreshing info is ignored*/ 1013 GF_RTI_SYSTEM_MEMORY_ONLY = 1<<2 1014 }; 1015 1016 /*! 1017 \brief Gets Run-Time info 1018 1019 Gets CPU and memory usage info for the calling process and the system. Information gathering is controled through timeout values. 1020 \param refresh_time_ms refresh time period in milliseconds. If the last sampling was done less than this period ago, the run-time info is not refreshed. 1021 \param rti holder to the run-time info structure to update. 1022 \param flags specify which info is to be retrieved. 1023 \return 1 if info has been updated, 0 otherwise. 1024 \note You should not try to use a too small refresh time. Typical values are 500 ms or one second. 1025 */ 1026 Bool gf_sys_get_rti(u32 refresh_time_ms, GF_SystemRTInfo *rti, u32 flags); 1027 1028 /*! @} */ 1029 1030 /*! 1031 \addtogroup osfile_grp 1032 \brief File System tools 1033 1034 This section documents file system tools used in GPAC. 1035 1036 FILE objects are wrapped in GPAC for direct memory or callback operations. All file functions not using stderr/stdout must use the gf_ prefixed versions, eg: 1037 \code 1038 //bad design, will fail when using wrapped memory IOs 1039 FILE *t = fopen(url, "rb"); 1040 fputs(t, mystring); 1041 fclose(t); 1042 1043 //good design, will work fine when using wrapped memory IOs 1044 FILE *t = gf_fopen(url, "rb"); 1045 gf_fputs(t, mystring); 1046 gf_fclose(t); 1047 \endcode 1048 1049 @{ 1050 */ 1051 1052 /*! 1053 \brief reads a file into memory 1054 1055 Reads a local file into memory, in binary open mode. 1056 \param file_name path on disk of the file to read 1057 \param out_data pointer to allocted address, to be freed by caller 1058 \param out_size pointer to allocted size 1059 \return error code if any 1060 */ 1061 GF_Err gf_file_load_data(const char *file_name, u8 **out_data, u32 *out_size); 1062 1063 /*! 1064 \brief reads a file into memory 1065 1066 Reads a local file into memory, in binary open mode. 1067 \param file stream object to read (no seek is performed) 1068 \param out_data pointer to allocted address, to be freed by caller 1069 \param out_size pointer to allocted size 1070 \return error code if any 1071 */ 1072 GF_Err gf_file_load_data_filep(FILE *file, u8 **out_data, u32 *out_size); 1073 1074 /*! 1075 \brief Delete Directory 1076 1077 Delete a dir within the full path. 1078 \param DirPathName the file path name. 1079 \return error if any 1080 */ 1081 GF_Err gf_rmdir(const char *DirPathName); 1082 1083 /*! 1084 \brief Create Directory 1085 1086 Create a directory within the full path. 1087 \param DirPathName the dir path name. 1088 \return error if any 1089 */ 1090 GF_Err gf_mkdir(const char* DirPathName); 1091 1092 /*! 1093 \brief Check Directory Exists 1094 1095 Create a directory within the full path. 1096 \param DirPathName the dir path name. 1097 \return GF_TRUE if directory exists 1098 */ 1099 Bool gf_dir_exists(const char *DirPathName); 1100 1101 /*! 1102 \brief Create Directory 1103 1104 Cleanup a directory within the full path, removing all the files and the directories. 1105 \param DirPathName the dir path name. 1106 \return error if any 1107 */ 1108 GF_Err gf_cleanup_dir(const char* DirPathName); 1109 1110 1111 /** 1112 Gets a newly allocated string containing the default cache directory. 1113 It is the responsibility of the caller to free the string. 1114 \return a fully qualified path to the default cache directory 1115 */ 1116 const char * gf_get_default_cache_directory(); 1117 1118 /** 1119 Gets the number of open file handles (gf_fopen/gf_fclose only). 1120 \return number of open file handles 1121 */ 1122 u32 gf_file_handles_count(); 1123 1124 /*! 1125 \brief file writing helper 1126 1127 Wrapper to properly handle calls to fwrite(), ensuring proper error handling is invoked when it fails. 1128 \param ptr data buffer to write 1129 \param nb_bytes number of bytes to write 1130 \param stream stream object 1131 \return number of bytes to written 1132 */ 1133 size_t gf_fwrite(const void *ptr, size_t nb_bytes, FILE *stream); 1134 1135 /*! 1136 \brief file reading helper 1137 1138 Wrapper to properly handle calls to fread() 1139 \param ptr data buffer to read 1140 \param nbytes number of bytes to read 1141 \param stream stream object 1142 \return number of bytes read 1143 */ 1144 size_t gf_fread(void *ptr, size_t nbytes, FILE *stream); 1145 1146 /*! 1147 \brief file reading helper 1148 1149 Wrapper to properly handle calls to fgets() 1150 \param buf same as fgets 1151 \param size same as fgets 1152 \param stream same as fgets 1153 \return same as fgets 1154 */ 1155 char *gf_fgets(char *buf, size_t size, FILE *stream); 1156 /*! 1157 \brief file reading helper 1158 1159 Wrapper to properly handle calls to fgetc() 1160 \param stream same as fgetc 1161 \return same as fgetc 1162 */ 1163 int gf_fgetc(FILE *stream); 1164 /*! 1165 \brief file writing helper 1166 1167 Wrapper to properly handle calls to fputc() 1168 \param val same as fputc 1169 \param stream same as fputc 1170 \return same as fputc 1171 */ 1172 int gf_fputc(int val, FILE *stream); 1173 /*! 1174 \brief file writing helper 1175 1176 Wrapper to properly handle calls to fputs() 1177 \param buf same as fputs 1178 \param stream same as fputs 1179 \return same as fputs 1180 */ 1181 int gf_fputs(const char *buf, FILE *stream); 1182 /*! 1183 \brief file writing helper 1184 1185 Wrapper to properly handle calls to fprintf() 1186 \param stream same as fprintf 1187 \param format same as fprintf 1188 \return same as fprintf 1189 */ 1190 int gf_fprintf(FILE *stream, const char *format, ...); 1191 /*! 1192 \brief file flush helper 1193 1194 Wrapper to properly handle calls to fflush() 1195 \param stream same as fflush 1196 \return same as fflush 1197 */ 1198 int gf_fflush(FILE *stream); 1199 /*! 1200 \brief end of file helper 1201 1202 Wrapper to properly handle calls to feof() 1203 \param stream same as feof 1204 \return same as feof 1205 */ 1206 int gf_feof(FILE *stream); 1207 /*! 1208 \brief file error helper 1209 1210 Wrapper to properly handle calls to ferror() 1211 \param stream same as ferror 1212 \return same as ferror 1213 */ 1214 int gf_ferror(FILE *stream); 1215 1216 /*! 1217 \brief file size helper 1218 1219 Gets the file size given a FILE object. The FILE object position will be reset to 0 after this call 1220 \param fp FILE object to check 1221 \return file size in bytes 1222 */ 1223 u64 gf_fsize(FILE *fp); 1224 1225 /*! 1226 \brief file IO helper 1227 1228 Checks if the given FILE object is a native FILE or a GF_FileIO wrapper. 1229 \param fp FILE object to check 1230 \return GF_TRUE if the FILE object is a wrapper to GF_FileIO 1231 */ 1232 Bool gf_fileio_check(FILE *fp); 1233 1234 /*! 1235 \brief file opening 1236 1237 Opens a file, potentially bigger than 4GB. if filename identifies a blob (gmem://), the blob will be opened 1238 \param file_name same as fopen 1239 \param mode same as fopen 1240 \return stream handle of the file object 1241 */ 1242 FILE *gf_fopen(const char *file_name, const char *mode); 1243 1244 /*! 1245 \brief file opening 1246 1247 Opens a file, potentially using file IO if the parent URL is a File IO wrapper 1248 \param file_name same as fopen 1249 \param parent_url URL of parent file. If not a file io wrapper (gfio://), the function is equivalent to gf_fopen 1250 \param mode same as fopen 1251 \return stream handle of the file object 1252 \note You only need to call this function if you're suspecting the file to be a large one (usually only media files), otherwise use regular stdio. 1253 \return stream habdle of the file or file IO object*/ 1254 FILE *gf_fopen_ex(const char *file_name, const char *parent_url, const char *mode); 1255 1256 /*! 1257 \brief file closing 1258 1259 Closes a file 1260 \note You only need to call this function if you're suspecting the file to be a large one (usually only media files), otherwise use regular stdio. 1261 \param file file to close 1262 \return same as flcose 1263 */ 1264 s32 gf_fclose(FILE *file); 1265 1266 /*! 1267 \brief large file position query 1268 1269 Queries the current read/write position in a large file 1270 \param f Same semantics as gf_ftell 1271 \return position in the file 1272 \note You only need to call this function if you're suspecting the file to be a large one (usually only media files), otherwise use regular stdio. 1273 */ 1274 u64 gf_ftell(FILE *f); 1275 /*! 1276 \brief large file seeking 1277 1278 Seeks the current read/write position in a large file 1279 \param f Same semantics as fseek 1280 \param pos Same semantics as fseek 1281 \param whence Same semantics as fseek 1282 \return 0 if success, -1 if error 1283 \note You only need to call this function if you're suspecting the file to be a large one (usually only media files), otherwise use regular stdio. 1284 */ 1285 s32 gf_fseek(FILE *f, s64 pos, s32 whence); 1286 1287 1288 /*! gets basename from filename/path 1289 \param filename Path of the file, can be an absolute path 1290 \return a pointer to the start of a filepath basename or null 1291 */ 1292 char* gf_file_basename(const char* filename); 1293 1294 /*! gets extension from filename 1295 \param filename Path of the file, can be an absolute path 1296 \return a pointer to the start of a filepath extension or null 1297 */ 1298 char* gf_file_ext_start(const char* filename); 1299 1300 1301 /*!\brief FileEnum info object 1302 1303 The FileEnumInfo object is used to get file attributes upon enumeration of a directory. 1304 */ 1305 typedef struct 1306 { 1307 /*!File is marked as hidden*/ 1308 Bool hidden; 1309 /*!File is a directory*/ 1310 Bool directory; 1311 /*!File is a drive mountpoint*/ 1312 Bool drive; 1313 /*!File is a system file*/ 1314 Bool system; 1315 /*!File size in bytes*/ 1316 u64 size; 1317 /*!File last modif time in UTC seconds*/ 1318 u64 last_modified; 1319 } GF_FileEnumInfo; 1320 1321 /*! 1322 \brief Directory Enumeration Callback 1323 1324 The gf_enum_dir_item type is the type for the callback of the \ref gf_enum_directory function 1325 \param cbck Opaque user data. 1326 \param item_name File or directory name. 1327 \param item_path File or directory full path and name from filesystem root. 1328 \param file_info information for the file or directory. 1329 \return 1 to abort enumeration, 0 to continue enumeration. 1330 * 1331 */ 1332 typedef Bool (*gf_enum_dir_item)(void *cbck, char *item_name, char *item_path, GF_FileEnumInfo *file_info); 1333 /*! 1334 \brief Directory enumeration 1335 1336 Enumerates a directory content. Feedback is provided by the enum_dir_item function 1337 \param dir Directory to enumerate 1338 \param enum_directory If set, only directories will be enumerated, otherwise only files are. 1339 \param enum_dir gf_enum_dir_item callback function for enumeration. 1340 \param cbck Opaque user data passed to callback function. 1341 \param filter optional filter for file extensions. If a file extension without the dot '.' character is not found in the 1342 * filter the file will be skipped. 1343 \return error if any 1344 */ 1345 GF_Err gf_enum_directory(const char *dir, Bool enum_directory, gf_enum_dir_item enum_dir, void *cbck, const char *filter); 1346 1347 1348 /*! 1349 \brief File Deletion 1350 1351 Deletes a file from the disk. 1352 \param fileName absolute name of the file or name relative to the current working directory. 1353 \return error if any 1354 */ 1355 GF_Err gf_file_delete(const char *fileName); 1356 1357 /*! 1358 \brief File Move 1359 1360 Moves or renames a file or directory. 1361 \param fileName absolute path of the file / directory to move or rename 1362 \param newFileName absolute new path/name of the file / directory 1363 \return error if any 1364 */ 1365 GF_Err gf_file_move(const char *fileName, const char *newFileName); 1366 1367 /*! 1368 \brief Temporary File Creation 1369 1370 Creates a new temporary file in binary mode 1371 \param fileName if not NULL, strdup() of the temporary filename when created by GPAC (NULL otherwise as the system automatically removes its own tmp files) 1372 \return stream handle to the new file ressoucre 1373 */ 1374 FILE *gf_file_temp(char ** const fileName); 1375 1376 1377 /*! 1378 \brief File Modification Time 1379 1380 Gets the modification time of the given file. The exact meaning of this value is system dependent 1381 \param filename file to check 1382 \return modification time of the file 1383 */ 1384 u64 gf_file_modification_time(const char *filename); 1385 1386 /*! 1387 \brief File existence check 1388 1389 Checks if file with given name exists 1390 \param fileName path of the file to check 1391 \return GF_TRUE if file exists */ 1392 Bool gf_file_exists(const char *fileName); 1393 1394 /*! 1395 \brief File existence check 1396 1397 Checks if file with given name exists, for regular files or File IO wrapper 1398 \param file_name path of the file to check 1399 \param par_name name of the parent file 1400 \return GF_TRUE if file exists */ 1401 Bool gf_file_exists_ex(const char *file_name, const char *par_name); 1402 1403 /*! File IO wrapper object*/ 1404 typedef struct __gf_file_io GF_FileIO; 1405 1406 1407 /*! open proc for memory file IO 1408 \param fileio_ref reference file_io. A file can be opened multiple times for the same reference, your code must handle this 1409 \param url target file name. 1410 \param mode opening mode of file, same as fopen mode. The following additionnal modes are defined: 1411 - "ref": indicates this FileIO object is used by some part of the code and must not be destroyed upon closing of the file. Associated URL is null 1412 - "unref": indicates this FileIO object is not used by some part of the code and may be destroyed if no more references to this object are set. Associated URL is null 1413 - "url": indicates to create a new FileIO object for the given URL without opening the output file. The resulting FileIO object must be garbage collected by the app in case its is never used by the callers 1414 - "probe": checks if the file exists, but no need to open the file. The function should return NULL in this case. If file does not exist, set out_error to GF_URL_ERROR 1415 \param out_error must be set to error code if any (never NULL) 1416 \return the opened GF_FileIO if success, or NULL otherwise 1417 */ 1418 typedef GF_FileIO *(*gfio_open_proc)(GF_FileIO *fileio_ref, const char *url, const char *mode, GF_Err *out_error); 1419 1420 /*! seek proc for memory file IO 1421 \param fileio target file IO object 1422 \param offset offset in file 1423 \param whence position from offset, same as fseek 1424 \return error if any 1425 */ 1426 typedef GF_Err (*gfio_seek_proc)(GF_FileIO *fileio, u64 offset, s32 whence); 1427 1428 /*! read proc for memory file IO 1429 \param fileio target file IO object 1430 \param buffer buffer to read. 1431 \param bytes number of bytes to read. 1432 \return number of bytes read, 0 if error. 1433 */ 1434 typedef u32 (*gfio_read_proc)(GF_FileIO *fileio, u8 *buffer, u32 bytes); 1435 1436 /*! write proc for memory file IO 1437 \param fileio target file IO object 1438 \param buffer buffer to write. 1439 \param bytes number of bytes to write. If 0, acts as fflush 1440 \return number of bytes write, 0 if error 1441 */ 1442 typedef u32 (*gfio_write_proc)(GF_FileIO *fileio, u8 *buffer, u32 bytes); 1443 1444 /*! positon tell proc for memory file IO 1445 \param fileio target file IO object 1446 \return position in bytes from file start 1447 */ 1448 typedef s64 (*gfio_tell_proc)(GF_FileIO *fileio); 1449 /*! end of file proc for memory file IO 1450 \param fileio target file IO object 1451 \return GF_TRUE if end of file, GF_FALSE otherwise 1452 */ 1453 typedef Bool (*gfio_eof_proc)(GF_FileIO *fileio); 1454 /*! printf proc for memory file IO 1455 \param fileio target file IO object 1456 \param format format string to use 1457 \param args variable argument list for printf, already initialized (va_start called) 1458 \return same as vfprint 1459 */ 1460 typedef int (*gfio_printf_proc)(GF_FileIO *fileio, const char *format, va_list args); 1461 1462 /*! Creates a new file IO object 1463 1464 There is no guarantee that the corresponding resource will be opened by the framework, it is therefore the caller responsability to track objects created by 1465 gf_fileio_new or as a response to open with mode "url". 1466 1467 \param url the original URL this file IO object wraps 1468 \param udta opaque data for caller 1469 \param open open proc for IO, must not be NULL 1470 \param seek seek proc for IO, must not be NULL 1471 \param read read proc for IO - if NULL the file is considered write only 1472 \param write write proc for IO - if NULL the file is considered read only 1473 \param tell tell proc for IO, must not be NULL 1474 \param eof eof proc for IO, must not be NULL 1475 \param printf printf proc for IO, may be NULL 1476 \return the newly created file IO wrapper 1477 */ 1478 GF_FileIO *gf_fileio_new(char *url, void *udta, 1479 gfio_open_proc open, 1480 gfio_seek_proc seek, 1481 gfio_read_proc read, 1482 gfio_write_proc write, 1483 gfio_tell_proc tell, 1484 gfio_eof_proc eof, 1485 gfio_printf_proc printf); 1486 1487 /*! Deletes a new fileIO object 1488 \param fileio the File IO object to delete 1489 */ 1490 void gf_fileio_del(GF_FileIO *fileio); 1491 1492 /*! Gets associated user data of a fileIO object 1493 \param fileio target file IO object 1494 \return the associated user data 1495 */ 1496 void *gf_fileio_get_udta(GF_FileIO *fileio); 1497 1498 /*! Gets URL of a fileIO object. 1499 The url uses the protocol scheme "gfio://" 1500 \param fileio target file IO object 1501 \return the file IO url to use 1502 */ 1503 const char * gf_fileio_url(GF_FileIO *fileio); 1504 1505 /*! Sets statistics on a fileIO object. 1506 \param fileio target file IO object 1507 \param bytes_done number of bytes fetched for this file 1508 \param file_size total size of this file, 0 if unknown 1509 \param cache_complete if GF_TRUE, means the file is completely available 1510 \param bytes_per_sec reception bytes per second, 0 if unknown 1511 */ 1512 void gf_fileio_set_stats(GF_FileIO *fileio, u64 bytes_done, u64 file_size, Bool cache_complete, u32 bytes_per_sec); 1513 1514 /*! Gets statistics on a fileIO object. 1515 \param fileio target file IO object 1516 \param bytes_done number of bytes fetched for this file (may be NULL) 1517 \param file_size total size of this file, 0 if unknown (may be NULL) 1518 \param cache_complete if GF_TRUE, means the file is completely available (may be NULL) 1519 \param bytes_per_sec reception bytes per second, 0 if unknown (may be NULL) 1520 \return GF_TRUE if success, GF_FALSE otherwise 1521 */ 1522 Bool gf_fileio_get_stats(GF_FileIO *fileio, u64 *bytes_done, u64 *file_size, Bool *cache_complete, u32 *bytes_per_sec); 1523 1524 /*! Checks if a FileIO object can write 1525 \param fileio target file IO object 1526 \param url the original resource URL to open 1527 \param mode the desired open mode 1528 \param out_err set to error code if any, must not be NULL 1529 \return file IO object for this resource 1530 */ 1531 GF_FileIO *gf_fileio_open_url(GF_FileIO *fileio, const char *url, const char *mode, GF_Err *out_err); 1532 1533 /*! Gets GF_FileIO object from its URL 1534 The url uses the protocol scheme "gfio://" 1535 \param url the URL of the File IO object 1536 \return the file IO object 1537 */ 1538 GF_FileIO *gf_fileio_from_url(const char *url); 1539 1540 /*! Constructs a new GF_FileIO object from a URL 1541 The url can be absolute or relative to the parent GF_FileIO. This is typcically needed by filters (dash input, dasher, NHML/NHNT writers...) generating or consuming additionnal files associated with the main file IO object but being written or read by other filters. 1542 The function will not open the associated resource, only create the file IO wrapper for later usage 1543 If you need to create a new fileIO to be opened immediately, use \ref gf_fopen_ex. 1544 1545 \param fileio parent file IO object 1546 \param new_res_url the original URL of the new object to create 1547 \return the url (gfio://) of the created file IO object, NULL otherwise 1548 */ 1549 const char *gf_fileio_factory(GF_FileIO *fileio, const char *new_res_url); 1550 1551 /*! Translates a FileIO object URL into the original resource URL 1552 \param url the URL of the File IO object 1553 \return the original resource URL associated with the file IO object 1554 */ 1555 const char * gf_fileio_translate_url(const char *url); 1556 /*! Gets a FileIO original resource URL 1557 \param fileio target file IO object 1558 \return the original resource URL associated with the file IO object 1559 */ 1560 const char * gf_fileio_resource_url(GF_FileIO *fileio); 1561 1562 /*! Checks if a FileIO object can read 1563 \param fileio target file IO object 1564 \return GF_TRUE if read is enabled on this object 1565 */ 1566 Bool gf_fileio_read_mode(GF_FileIO *fileio); 1567 /*! Checks if a FileIO object can write 1568 \param fileio target file IO object 1569 \return GF_TRUE if write is enabled on this object 1570 */ 1571 Bool gf_fileio_write_mode(GF_FileIO *fileio); 1572 1573 /*! @} */ 1574 1575 /*! 1576 \addtogroup hash_grp 1577 \brief Data hashing, integrity and generic compression 1578 1579 This section documents misc data functions such as integrity and parsing such as SHA-1 hashing CRC checksum, 128 bit ID parsing... 1580 1581 @{ 1582 */ 1583 1584 1585 /*! 1586 \brief CRC32 compute 1587 1588 Computes the CRC32 value of a buffer. 1589 \param data buffer 1590 \param size buffer size 1591 \return computed CRC32 1592 */ 1593 u32 gf_crc_32(const u8 *data, u32 size); 1594 1595 1596 /** 1597 Compresses a data buffer in place using zlib/deflate. Buffer may be reallocated in the process. 1598 \param data pointer to the data buffer to be compressed 1599 \param data_len length of the data buffer to be compressed 1600 \param out_size pointer for output buffer size 1601 \return error if any 1602 */ 1603 GF_Err gf_gz_compress_payload(u8 **data, u32 data_len, u32 *out_size); 1604 1605 #ifndef GPAC_DISABLE_ZLIB 1606 /** 1607 Compresses a data buffer in place using zlib/deflate. Buffer may be reallocated in the process. 1608 \param data pointer to the data buffer to be compressed 1609 \param data_len length of the data buffer to be compressed 1610 \param out_size pointer for output buffer size 1611 \param data_offset offset in source buffer - the input payload size is data_len - data_offset 1612 \param skip_if_larger if GF_TRUE, will not override source buffer if compressed version is larger than input data 1613 \return error if any 1614 */ 1615 GF_Err gf_gz_compress_payload_ex(u8 **data, u32 data_len, u32 *out_size, u8 data_offset, Bool skip_if_larger); 1616 #endif /*GPAC_DISABLE_ZLIB*/ 1617 1618 /** 1619 Decompresses a data buffer using zlib/deflate. 1620 \param data data buffer to be decompressed 1621 \param data_len length of the data buffer to be decompressed 1622 \param uncompressed_data pointer to the uncompressed data buffer. It is the responsibility of the caller to free this buffer. 1623 \param out_size size of the uncompressed buffer 1624 \return error if any 1625 */ 1626 GF_Err gf_gz_decompress_payload(u8 *data, u32 data_len, u8 **uncompressed_data, u32 *out_size); 1627 1628 /** 1629 Compresses a data buffer in place using LZMA. Buffer may be reallocated in the process. 1630 \param data pointer to the data buffer to be compressed 1631 \param data_len length of the data buffer to be compressed 1632 \param out_size pointer for output buffer size 1633 \return error if any 1634 */ 1635 GF_Err gf_lz_compress_payload(u8 **data, u32 data_len, u32 *out_size); 1636 1637 /** 1638 Decompresses a data buffer using LZMA. 1639 \param data data buffer to be decompressed 1640 \param data_len length of the data buffer to be decompressed 1641 \param uncompressed_data pointer to the uncompressed data buffer. It is the responsibility of the caller to free this buffer. 1642 \param out_size size of the uncompressed buffer 1643 \return error if any 1644 */ 1645 GF_Err gf_lz_decompress_payload(u8 *data, u32 data_len, u8 **uncompressed_data, u32 *out_size); 1646 1647 1648 #ifndef GPAC_DISABLE_ZLIB 1649 /*! Wrapper around gzseek, same parameters 1650 \param file target gzfile 1651 \param offset offset in file 1652 \param whence same as gzseek 1653 \return same as gzseek 1654 */ 1655 u64 gf_gzseek(void *file, u64 offset, int whence); 1656 /*! Wrapper around gf_gztell, same parameters 1657 \param file target gzfile 1658 \return postion in file 1659 */ 1660 u64 gf_gztell(void *file); 1661 /*! Wrapper around gzrewind, same parameters 1662 \param file target gzfile 1663 \return same as gzrewind 1664 */ 1665 s64 gf_gzrewind(void *file); 1666 /*! Wrapper around gzeof, same parameters 1667 \param file target gzfile 1668 \return same as gzeof 1669 */ 1670 int gf_gzeof(void *file); 1671 /*! Wrapper around gzclose, same parameters 1672 \param file target gzfile 1673 \return same as gzclose 1674 */ 1675 int gf_gzclose(void *file); 1676 /*! Wrapper around gzerror, same parameters 1677 \param file target gzfile 1678 \param errnum same as gzerror 1679 \return same as gzerror 1680 */ 1681 const char * gf_gzerror (void *file, int *errnum); 1682 /*! Wrapper around gzclearerr, same parameters 1683 \param file target gzfile 1684 */ 1685 void gf_gzclearerr(void *file); 1686 /*! Wrapper around gzopen, same parameters 1687 \param path the file name to open 1688 \param mode the file open mode 1689 \return open file 1690 */ 1691 void *gf_gzopen(const char *path, const char *mode); 1692 /*! Wrapper around gzread, same parameters 1693 \param file target gzfile 1694 \param buf same as gzread 1695 \param len same as gzread 1696 \return same as gzread 1697 */ 1698 int gf_gzread(void *file, void *buf, unsigned len); 1699 /*! Wrapper around gzdirect, same parameters 1700 \param file target gzfile 1701 \return same as gzdirect 1702 */ 1703 int gf_gzdirect(void *file); 1704 /*! Wrapper around gzgetc, same parameters 1705 \param file target gzfile 1706 \return same as gzgetc 1707 */ 1708 int gf_gzgetc(void *file); 1709 /*! Wrapper around gzgets, same parameters 1710 \param file target gzfile 1711 \param buf same as gzread 1712 \param len same as gzread 1713 \return same as gzgets 1714 */ 1715 char * gf_gzgets(void *file, char *buf, int len); 1716 #endif 1717 1718 1719 /*! SHA1 context*/ 1720 typedef struct __sha1_context GF_SHA1Context; 1721 1722 /*! SHA1 message size */ 1723 #define GF_SHA1_DIGEST_SIZE 20 1724 1725 /*! create SHA-1 context 1726 \return the SHA1 context*/ 1727 GF_SHA1Context *gf_sha1_starts(); 1728 /*! adds byte to the SHA-1 context 1729 \param ctx the target SHA1 context 1730 \param input data to hash 1731 \param length size of data in bytes 1732 */ 1733 void gf_sha1_update(GF_SHA1Context *ctx, u8 *input, u32 length); 1734 /*! generates SHA-1 of all bytes ingested 1735 \param ctx the target SHA1 context 1736 \param digest buffer to store message digest 1737 */ 1738 void gf_sha1_finish(GF_SHA1Context *ctx, u8 digest[GF_SHA1_DIGEST_SIZE] ); 1739 1740 /*! gets SHA1 message digest of a file 1741 \param filename name of file to hash 1742 \param digest buffer to store message digest 1743 \return error if any 1744 */ 1745 GF_Err gf_sha1_file(const char *filename, u8 digest[GF_SHA1_DIGEST_SIZE]); 1746 1747 /*! gets SHA-1 of input buffer 1748 \param buf input buffer to hash 1749 \param buflen sizeo of input buffer in bytes 1750 \param digest buffer to store message digest 1751 */ 1752 void gf_sha1_csum(u8 *buf, u32 buflen, u8 digest[GF_SHA1_DIGEST_SIZE]); 1753 /*! @} */ 1754 1755 1756 /*! 1757 \addtogroup libsys_grp 1758 @{ 1759 */ 1760 1761 /*! gets a global config key value from its section and name. 1762 \param secName the desired key parent section name 1763 \param keyName the desired key name 1764 \return the desired key value if found, NULL otherwise. 1765 */ 1766 const char *gf_opts_get_key(const char *secName, const char *keyName); 1767 1768 /*! sets a global config key value from its section and name. 1769 \param secName the desired key parent section name 1770 \param keyName the desired key name 1771 \param keyValue the desired key value 1772 \note this will also create both section and key if they are not found in the configuration file 1773 \return error if any 1774 */ 1775 GF_Err gf_opts_set_key(const char *secName, const char *keyName, const char *keyValue); 1776 1777 /*! removes all entries in the given section of the global config 1778 \param secName the target section 1779 */ 1780 void gf_opts_del_section(const char *secName); 1781 /*! gets the number of sections in the global config 1782 \return the number of sections 1783 */ 1784 u32 gf_opts_get_section_count(); 1785 /*! gets a section name based on its index in the global config 1786 \param secIndex 0-based index of the section to query 1787 \return the section name if found, NULL otherwise 1788 */ 1789 const char *gf_opts_get_section_name(u32 secIndex); 1790 1791 /*! gets the number of keys in a section of the global config 1792 \param secName the target section 1793 \return the number of keys in the section 1794 */ 1795 u32 gf_opts_get_key_count(const char *secName); 1796 /*! gets the number of keys in a section of the global config 1797 \param secName the target section 1798 \param keyIndex 0-based index of the key in the section 1799 \return the key name if found, NULL otherwise 1800 */ 1801 const char *gf_opts_get_key_name(const char *secName, u32 keyIndex); 1802 1803 /*! gets a global config boolean value from its section and name. 1804 \param secName the desired key parent section name 1805 \param keyName the desired key name 1806 \return the desired key value if found, GF_FALSE otherwise. 1807 */ 1808 Bool gf_opts_get_bool(const char *secName, const char *keyName); 1809 1810 /*! gets a global config integer value from its section and name. 1811 \param secName the desired key parent section name 1812 \param keyName the desired key name 1813 \return the desired key value if found, 0 otherwise. 1814 */ 1815 u32 gf_opts_get_int(const char *secName, const char *keyName); 1816 1817 /*! gets a global config key value from its section and name. 1818 \param secName the desired key parent section name 1819 \param keyName the desired key name 1820 \return the desired key value if found and if the key is not restricted, NULL otherwise. 1821 */ 1822 const char *gf_opts_get_key_restricted(const char *secName, const char *keyName); 1823 1824 /*! 1825 * Do not save modification to global options 1826 \return error code 1827 */ 1828 GF_Err gf_opts_discard_changes(); 1829 1830 /*! 1831 * Returns file name of global config 1832 \return file name of global config or NULL if libgpac is not initialized 1833 */ 1834 const char *gf_opts_get_filename(); 1835 1836 /*! 1837 * Gets GPAC shared directory (gui, shaders, etc ..) 1838 \param path_buffer GF_MAX_PATH buffer to store output 1839 \return GF_TRUE if success, GF_FALSE otherwise 1840 */ 1841 Bool gf_opts_default_shared_directory(char *path_buffer); 1842 1843 /*! @} */ 1844 1845 1846 //! @cond Doxygen_Suppress 1847 1848 #ifdef GPAC_DISABLE_3D 1849 #define GPAC_DISABLE_REMOTERY 1 1850 #endif 1851 1852 #ifdef GPAC_DISABLE_REMOTERY 1853 #define RMT_ENABLED 0 1854 #else 1855 #define RMT_USE_OPENGL 1 1856 #endif 1857 1858 #include <gpac/Remotery.h> 1859 1860 #define GF_RMT_AGGREGATE RMTSF_Aggregate 1861 /*! begins remotery CPU sample*/ 1862 #define gf_rmt_begin rmt_BeginCPUSample 1863 /*! begins remotery CPU sample with hash*/ 1864 #define gf_rmt_begin_hash rmt_BeginCPUSampleStore 1865 /*! ends remotery CPU sample*/ 1866 #define gf_rmt_end rmt_EndCPUSample 1867 /*! sets remotery thread name*/ 1868 #define gf_rmt_set_thread_name rmt_SetCurrentThreadName 1869 /*! logs remotery text*/ 1870 #define gf_rmt_log_text rmt_LogText 1871 /*! begins remotery OpenGL sample*/ 1872 #define gf_rmt_begin_gl rmt_BeginOpenGLSample 1873 /*! begins remotery OpenGL sample with hash*/ 1874 #define gf_rmt_begin_gl_hash rmt_BeginOpenGLSampleStore 1875 /*!ends remotery OpenGL sample*/ 1876 #define gf_rmt_end_gl rmt_EndOpenGLSample 1877 1878 //! @endcond 1879 1880 /* \cond dummy */ 1881 #ifdef GPAC_CONFIG_ANDROID 1882 typedef void (*fm_callback_func)(void *cbk_obj, u32 type, u32 param, int *value); 1883 extern void gf_fm_request_set_callback(void *cbk_obj, fm_callback_func cbk_func); 1884 void gf_fm_request_call(u32 type, u32 param, int *value); 1885 #endif //GPAC_CONFIG_ANDROID 1886 1887 /*to call whenever the OpenGL library is opened - this function is needed to bind openGL and remotery, and to load 1888 openGL extensions on windows 1889 not exported, and not included in src/compositor/gl_inc.h since it may be needed even when no OpenGL 1890 calls are made by the caller*/ 1891 void gf_opengl_init(); 1892 1893 typedef enum 1894 { 1895 //pbo not enabled 1896 GF_GL_PBO_NONE=0, 1897 //pbo enabled, both push and glTexImage textures are done in gf_gl_txw_upload 1898 GF_GL_PBO_BOTH, 1899 //push only is done in gf_gl_txw_upload 1900 GF_GL_PBO_PUSH, 1901 // glTexImage textures only is done in gf_gl_txw_upload 1902 GF_GL_PBO_TEXIMG, 1903 } GF_GLPBOState; 1904 1905 typedef struct _gl_texture_wrap 1906 { 1907 u32 textures[4]; 1908 u32 PBOs[4]; 1909 1910 u32 nb_textures; 1911 u32 width, height, pix_fmt, stride, uv_stride; 1912 Bool is_yuv; 1913 u32 bit_depth, uv_w, uv_h; 1914 u32 scale_10bit; 1915 1916 u32 gl_format; 1917 u32 bytes_per_pix; 1918 Bool has_alpha; 1919 Bool internal_textures; 1920 Bool uniform_setup; 1921 u32 memory_format; 1922 struct _gf_filter_frame_interface *frame_ifce; 1923 Bool first_tx_load; 1924 1925 //PBO state - must be managed by caller, especially if using seperated push and texImg steps through gf_gl_txw_setup calls 1926 GF_GLPBOState pbo_state; 1927 Bool flip; 1928 } GF_GLTextureWrapper; 1929 1930 Bool gf_gl_txw_insert_fragment_shader(u32 pix_fmt, const char *tx_name, char **f_source); 1931 Bool gf_gl_txw_setup(GF_GLTextureWrapper *tx, u32 pix_fmt, u32 width, u32 height, u32 stride, u32 uv_stride, Bool linear_interp, struct _gf_filter_frame_interface *frame_ifce); 1932 Bool gf_gl_txw_upload(GF_GLTextureWrapper *tx, const u8 *data, struct _gf_filter_frame_interface *frame_ifce); 1933 Bool gf_gl_txw_bind(GF_GLTextureWrapper *tx, const char *tx_name, u32 gl_program, u32 texture_unit); 1934 void gf_gl_txw_reset(GF_GLTextureWrapper *tx); 1935 1936 /* \endcond */ 1937 1938 1939 /*! macros to get the size of an array of struct*/ 1940 #define GF_ARRAY_LENGTH(a) (sizeof(a) / sizeof((a)[0])) 1941 1942 #ifdef __cplusplus 1943 } 1944 #endif 1945 1946 1947 #endif /*_GF_CORE_H_*/ 1948 1949