comparison: src/cx/properties.h
src/cx/properties.h
- changeset 985
- 68754c7de906
- parent 980
- 98af3fbc847f
equal
deleted
inserted
replaced
| 984:e8f354a25ac8 | 985:68754c7de906 |
|---|---|
| 225 * @param sink the sink | 225 * @param sink the sink |
| 226 * @param key the key | 226 * @param key the key |
| 227 * @param value the value | 227 * @param value the value |
| 228 * @return zero on success, non-zero when sinking the k/v-pair failed | 228 * @return zero on success, non-zero when sinking the k/v-pair failed |
| 229 */ | 229 */ |
| 230 __attribute__((__nonnull__)) | 230 cx_attr_nonnull |
| 231 typedef int(*cx_properties_sink_func)( | 231 typedef int(*cx_properties_sink_func)( |
| 232 CxProperties *prop, | 232 CxProperties *prop, |
| 233 CxPropertiesSink *sink, | 233 CxPropertiesSink *sink, |
| 234 cxstring key, | 234 cxstring key, |
| 235 cxstring value | 235 cxstring value |
| 271 * @param prop the properties interface that wants to read from the source | 271 * @param prop the properties interface that wants to read from the source |
| 272 * @param src the source | 272 * @param src the source |
| 273 * @param target a string buffer where the read data shall be stored | 273 * @param target a string buffer where the read data shall be stored |
| 274 * @return zero on success, non-zero when reading data failed | 274 * @return zero on success, non-zero when reading data failed |
| 275 */ | 275 */ |
| 276 __attribute__((__nonnull__)) | 276 cx_attr_nonnull |
| 277 typedef int(*cx_properties_read_func)( | 277 typedef int(*cx_properties_read_func)( |
| 278 CxProperties *prop, | 278 CxProperties *prop, |
| 279 CxPropertiesSource *src, | 279 CxPropertiesSource *src, |
| 280 cxstring *target | 280 cxstring *target |
| 281 ); | 281 ); |
| 285 * | 285 * |
| 286 * @param prop the properties interface that wants to read from the source | 286 * @param prop the properties interface that wants to read from the source |
| 287 * @param src the source | 287 * @param src the source |
| 288 * @return zero when initialization was successful, non-zero otherwise | 288 * @return zero when initialization was successful, non-zero otherwise |
| 289 */ | 289 */ |
| 290 __attribute__((__nonnull__)) | 290 cx_attr_nonnull |
| 291 typedef int(*cx_properties_read_init_func)( | 291 typedef int(*cx_properties_read_init_func)( |
| 292 CxProperties *prop, | 292 CxProperties *prop, |
| 293 CxPropertiesSource *src | 293 CxPropertiesSource *src |
| 294 ); | 294 ); |
| 295 | 295 |
| 297 * A function that cleans memory initialized by the read_init_func. | 297 * A function that cleans memory initialized by the read_init_func. |
| 298 * | 298 * |
| 299 * @param prop the properties interface that wants to read from the source | 299 * @param prop the properties interface that wants to read from the source |
| 300 * @param src the source | 300 * @param src the source |
| 301 */ | 301 */ |
| 302 __attribute__((__nonnull__)) | 302 cx_attr_nonnull |
| 303 typedef void(*cx_properties_read_clean_func)( | 303 typedef void(*cx_properties_read_clean_func)( |
| 304 CxProperties *prop, | 304 CxProperties *prop, |
| 305 CxPropertiesSource *src | 305 CxPropertiesSource *src |
| 306 ); | 306 ); |
| 307 | 307 |
| 343 * | 343 * |
| 344 * @param prop the properties interface | 344 * @param prop the properties interface |
| 345 * @param config the properties configuration | 345 * @param config the properties configuration |
| 346 * @see cxPropertiesInitDefault() | 346 * @see cxPropertiesInitDefault() |
| 347 */ | 347 */ |
| 348 __attribute__((__nonnull__)) | 348 cx_attr_nonnull |
| 349 void cxPropertiesInit(CxProperties *prop, CxPropertiesConfig config); | 349 void cxPropertiesInit(CxProperties *prop, CxPropertiesConfig config); |
| 350 | 350 |
| 351 /** | 351 /** |
| 352 * Destroys the properties interface. | 352 * Destroys the properties interface. |
| 353 * | 353 * |
| 357 * and you really don't want to search the entire code where you might need | 357 * and you really don't want to search the entire code where you might need |
| 358 * add call to this function. | 358 * add call to this function. |
| 359 * | 359 * |
| 360 * @param prop the properties interface | 360 * @param prop the properties interface |
| 361 */ | 361 */ |
| 362 __attribute__((__nonnull__)) | 362 cx_attr_nonnull |
| 363 void cxPropertiesDestroy(CxProperties *prop); | 363 void cxPropertiesDestroy(CxProperties *prop); |
| 364 | 364 |
| 365 /** | 365 /** |
| 366 * Initialize a properties parser with the default configuration. | 366 * Initialize a properties parser with the default configuration. |
| 367 * | 367 * |
| 386 * @param prop the properties interface | 386 * @param prop the properties interface |
| 387 * @param buf a pointer to data | 387 * @param buf a pointer to data |
| 388 * @param len the length of the data | 388 * @param len the length of the data |
| 389 * @return non-zero when a memory allocation was necessary but failed | 389 * @return non-zero when a memory allocation was necessary but failed |
| 390 */ | 390 */ |
| 391 __attribute__((__nonnull__)) | 391 cx_attr_nonnull |
| 392 cx_attr_access_r(2, 3) | |
| 392 int cxPropertiesFilln( | 393 int cxPropertiesFilln( |
| 393 CxProperties *prop, | 394 CxProperties *prop, |
| 394 const char *buf, | 395 const char *buf, |
| 395 size_t len | 396 size_t len |
| 396 ); | 397 ); |
| 420 * | 421 * |
| 421 * @param prop the properties interface | 422 * @param prop the properties interface |
| 422 * @param str the string | 423 * @param str the string |
| 423 * @return non-zero when a memory allocation was necessary but failed | 424 * @return non-zero when a memory allocation was necessary but failed |
| 424 */ | 425 */ |
| 425 __attribute__((__nonnull__)) | 426 cx_attr_nonnull |
| 426 static inline int cx_properties_fill_cxstr( | 427 static inline int cx_properties_fill_cxstr( |
| 427 CxProperties *prop, | 428 CxProperties *prop, |
| 428 cxstring str | 429 cxstring str |
| 429 ) { | 430 ) { |
| 430 return cxPropertiesFilln(prop, str.ptr, str.length); | 431 return cxPropertiesFilln(prop, str.ptr, str.length); |
| 435 * | 436 * |
| 436 * @param prop the properties interface | 437 * @param prop the properties interface |
| 437 * @param str the string | 438 * @param str the string |
| 438 * @return non-zero when a memory allocation was necessary but failed | 439 * @return non-zero when a memory allocation was necessary but failed |
| 439 */ | 440 */ |
| 440 __attribute__((__nonnull__)) | 441 cx_attr_nonnull |
| 441 static inline int cx_properties_fill_mutstr( | 442 static inline int cx_properties_fill_mutstr( |
| 442 CxProperties *prop, | 443 CxProperties *prop, |
| 443 cxmutstr str | 444 cxmutstr str |
| 444 ) { | 445 ) { |
| 445 return cxPropertiesFilln(prop, str.ptr, str.length); | 446 return cxPropertiesFilln(prop, str.ptr, str.length); |
| 450 * | 451 * |
| 451 * @param prop the properties interface | 452 * @param prop the properties interface |
| 452 * @param str the string | 453 * @param str the string |
| 453 * @return non-zero when a memory allocation was necessary but failed | 454 * @return non-zero when a memory allocation was necessary but failed |
| 454 */ | 455 */ |
| 455 __attribute__((__nonnull__)) | 456 cx_attr_nonnull |
| 457 cx_attr_cstr_arg(2) | |
| 456 static inline int cx_properties_fill_str( | 458 static inline int cx_properties_fill_str( |
| 457 CxProperties *prop, | 459 CxProperties *prop, |
| 458 const char *str | 460 const char *str |
| 459 ) { | 461 ) { |
| 460 return cxPropertiesFilln(prop, str, strlen(str)); | 462 return cxPropertiesFilln(prop, str, strlen(str)); |
| 465 * | 467 * |
| 466 * @param prop the properties interface | 468 * @param prop the properties interface |
| 467 * @param buf a pointer to stack memory | 469 * @param buf a pointer to stack memory |
| 468 * @param capacity the capacity of the stack memory | 470 * @param capacity the capacity of the stack memory |
| 469 */ | 471 */ |
| 470 __attribute__((__nonnull__)) | 472 cx_attr_nonnull |
| 471 void cxPropertiesUseStack( | 473 void cxPropertiesUseStack( |
| 472 CxProperties *prop, | 474 CxProperties *prop, |
| 473 char *buf, | 475 char *buf, |
| 474 size_t capacity | 476 size_t capacity |
| 475 ); | 477 ); |
| 492 * @param key a pointer to the cxstring that shall contain the property name | 494 * @param key a pointer to the cxstring that shall contain the property name |
| 493 * @param value a pointer to the cxstring that shall contain the property value | 495 * @param value a pointer to the cxstring that shall contain the property value |
| 494 * @return the status code as defined above | 496 * @return the status code as defined above |
| 495 * @see cxPropertiesFill() | 497 * @see cxPropertiesFill() |
| 496 */ | 498 */ |
| 497 __attribute__((__nonnull__, __warn_unused_result__)) | 499 cx_attr_nonnull |
| 500 cx_attr_nodiscard | |
| 498 CxPropertiesStatus cxPropertiesNext( | 501 CxPropertiesStatus cxPropertiesNext( |
| 499 CxProperties *prop, | 502 CxProperties *prop, |
| 500 cxstring *key, | 503 cxstring *key, |
| 501 cxstring *value | 504 cxstring *value |
| 502 ); | 505 ); |
| 511 * | 514 * |
| 512 * @param map the map that shall consume the k/v-pairs. | 515 * @param map the map that shall consume the k/v-pairs. |
| 513 * @return the sink | 516 * @return the sink |
| 514 * @see cxPropertiesLoad() | 517 * @see cxPropertiesLoad() |
| 515 */ | 518 */ |
| 516 __attribute__((__nonnull__, __warn_unused_result__)) | 519 cx_attr_nonnull |
| 520 cx_attr_nodiscard | |
| 517 CxPropertiesSink cxPropertiesMapSink(CxMap *map); | 521 CxPropertiesSink cxPropertiesMapSink(CxMap *map); |
| 518 | 522 |
| 519 /** | 523 /** |
| 520 * Creates a properties source based on an UCX string. | 524 * Creates a properties source based on an UCX string. |
| 521 * | 525 * |
| 522 * @param str the string | 526 * @param str the string |
| 523 * @return the properties source | 527 * @return the properties source |
| 524 * @see cxPropertiesLoad() | 528 * @see cxPropertiesLoad() |
| 525 */ | 529 */ |
| 526 __attribute__((__warn_unused_result__)) | 530 cx_attr_nodiscard |
| 527 CxPropertiesSource cxPropertiesStringSource(cxstring str); | 531 CxPropertiesSource cxPropertiesStringSource(cxstring str); |
| 528 | 532 |
| 529 /** | 533 /** |
| 530 * Creates a properties source based on C string with the specified length. | 534 * Creates a properties source based on C string with the specified length. |
| 531 * | 535 * |
| 532 * @param str the string | 536 * @param str the string |
| 533 * @param len the length | 537 * @param len the length |
| 534 * @return the properties source | 538 * @return the properties source |
| 535 * @see cxPropertiesLoad() | 539 * @see cxPropertiesLoad() |
| 536 */ | 540 */ |
| 537 __attribute__((__nonnull__, __warn_unused_result__)) | 541 cx_attr_nonnull |
| 542 cx_attr_nodiscard | |
| 543 cx_attr_access_r(1, 2) | |
| 538 CxPropertiesSource cxPropertiesCstrnSource(const char *str, size_t len); | 544 CxPropertiesSource cxPropertiesCstrnSource(const char *str, size_t len); |
| 539 | 545 |
| 540 /** | 546 /** |
| 541 * Creates a properties source based on a C string. | 547 * Creates a properties source based on a C string. |
| 542 * | 548 * |
| 545 * | 551 * |
| 546 * @param str the string | 552 * @param str the string |
| 547 * @return the properties source | 553 * @return the properties source |
| 548 * @see cxPropertiesLoad() | 554 * @see cxPropertiesLoad() |
| 549 */ | 555 */ |
| 550 __attribute__((__nonnull__, __warn_unused_result__)) | 556 cx_attr_nonnull |
| 557 cx_attr_nodiscard | |
| 558 cx_attr_cstr_arg(1) | |
| 551 CxPropertiesSource cxPropertiesCstrSource(const char *str); | 559 CxPropertiesSource cxPropertiesCstrSource(const char *str); |
| 552 | 560 |
| 553 /** | 561 /** |
| 554 * Creates a properties source based on an FILE. | 562 * Creates a properties source based on an FILE. |
| 555 * | 563 * |
| 557 * @param chunk_size how many bytes may be read in one operation | 565 * @param chunk_size how many bytes may be read in one operation |
| 558 * | 566 * |
| 559 * @return the properties source | 567 * @return the properties source |
| 560 * @see cxPropertiesLoad() | 568 * @see cxPropertiesLoad() |
| 561 */ | 569 */ |
| 562 __attribute__((__nonnull__, __warn_unused_result__)) | 570 cx_attr_nonnull |
| 571 cx_attr_nodiscard | |
| 572 cx_attr_access_r(1) | |
| 563 CxPropertiesSource cxPropertiesFileSource(FILE *file, size_t chunk_size); | 573 CxPropertiesSource cxPropertiesFileSource(FILE *file, size_t chunk_size); |
| 564 | 574 |
| 565 | 575 |
| 566 /** | 576 /** |
| 567 * Loads properties data from a source and transfers it to a sink. | 577 * Loads properties data from a source and transfers it to a sink. |
| 576 * @param prop the properties interface | 586 * @param prop the properties interface |
| 577 * @param sink the sink | 587 * @param sink the sink |
| 578 * @param source the source | 588 * @param source the source |
| 579 * @return the status of the last operation | 589 * @return the status of the last operation |
| 580 */ | 590 */ |
| 581 __attribute__((__nonnull__)) | 591 cx_attr_nonnull |
| 582 CxPropertiesStatus cxPropertiesLoad( | 592 CxPropertiesStatus cxPropertiesLoad( |
| 583 CxProperties *prop, | 593 CxProperties *prop, |
| 584 CxPropertiesSink sink, | 594 CxPropertiesSink sink, |
| 585 CxPropertiesSource source | 595 CxPropertiesSource source |
| 586 ); | 596 ); |
