Codebase list getdns / c613743
Update spec to 0.701 Willem Toorop 8 years ago
2 changed file(s) with 70 addition(s) and 70 deletion(s). Raw diff Collapse all Expand all
+27
-27
spec/index.html less more
521521 <div class=forh id="datagetters">
522522 /* Lists: get the length, get the data_type of the value at a given
523523 position, and get the data at a given position */
524 getdns_return_t getdns_list_get_length(const getdns_list *this_list, size_t *answer);
525 getdns_return_t getdns_list_get_data_type(const getdns_list *this_list, size_t index, getdns_data_type *answer);
526 getdns_return_t getdns_list_get_dict(const getdns_list *this_list, size_t index, getdns_dict **answer);
527 getdns_return_t getdns_list_get_list(const getdns_list *this_list, size_t index, getdns_list **answer);
528 getdns_return_t getdns_list_get_bindata(const getdns_list *this_list, size_t index, getdns_bindata **answer);
529 getdns_return_t getdns_list_get_int(const getdns_list *this_list, size_t index, uint32_t *answer);
524 getdns_return_t getdns_list_get_length(const getdns_list *list, size_t *answer);
525 getdns_return_t getdns_list_get_data_type(const getdns_list *list, size_t index, getdns_data_type *answer);
526 getdns_return_t getdns_list_get_dict(const getdns_list *list, size_t index, getdns_dict **answer);
527 getdns_return_t getdns_list_get_list(const getdns_list *list, size_t index, getdns_list **answer);
528 getdns_return_t getdns_list_get_bindata(const getdns_list *list, size_t index, getdns_bindata **answer);
529 getdns_return_t getdns_list_get_int(const getdns_list *list, size_t index, uint32_t *answer);
530530
531531 /* Dicts: get the list of names, get the data_type of the
532532 value at a given name, and get the data at a given name */
533 getdns_return_t getdns_dict_get_names(const getdns_dict *this_dict, getdns_list **answer);
534 getdns_return_t getdns_dict_get_data_type(const getdns_dict *this_dict, const char *name, getdns_data_type *answer);
535 getdns_return_t getdns_dict_get_dict(const getdns_dict *this_dict, const char *name, getdns_dict **answer);
536 getdns_return_t getdns_dict_get_list(const getdns_dict *this_dict, const char *name, getdns_list **answer);
537 getdns_return_t getdns_dict_get_bindata(const getdns_dict *this_dict, const char *name, getdns_bindata **answer);
538 getdns_return_t getdns_dict_get_int(const getdns_dict *this_dict, const char *name, uint32_t *answer);
533 getdns_return_t getdns_dict_get_names(const getdns_dict *dict, getdns_list **answer);
534 getdns_return_t getdns_dict_get_data_type(const getdns_dict *dict, const char *name, getdns_data_type *answer);
535 getdns_return_t getdns_dict_get_dict(const getdns_dict *dict, const char *name, getdns_dict **answer);
536 getdns_return_t getdns_dict_get_list(const getdns_dict *dict, const char *name, getdns_list **answer);
537 getdns_return_t getdns_dict_get_bindata(const getdns_dict *dict, const char *name, getdns_bindata **answer);
538 getdns_return_t getdns_dict_get_int(const getdns_dict *dict, const char *name, uint32_t *answer);
539539 </div>
540540
541541 <p>All of these helper getter functions return <code>GETDNS_RETURN_GOOD</code> if the call is successful.
582582 void *(*realloc)(void *userarg, void *, size_t),
583583 void (*free)(void *userarg, void *)
584584 );
585 void getdns_list_destroy(getdns_list *this_list);
586 getdns_return_t getdns_list_set_dict(getdns_list *this_list, size_t index, const getdns_dict *child_dict);
587 getdns_return_t getdns_list_set_list(getdns_list *this_list, size_t index, const getdns_list *child_list);
588 getdns_return_t getdns_list_set_bindata(getdns_list *this_list, size_t index, const getdns_bindata *child_bindata);
589 getdns_return_t getdns_list_set_int(getdns_list *this_list, size_t index, uint32_t child_uint32);
585 void getdns_list_destroy(getdns_list *list);
586 getdns_return_t getdns_list_set_dict(getdns_list *list, size_t index, const getdns_dict *child_dict);
587 getdns_return_t getdns_list_set_list(getdns_list *list, size_t index, const getdns_list *child_list);
588 getdns_return_t getdns_list_set_bindata(getdns_list *list, size_t index, const getdns_bindata *child_bindata);
589 getdns_return_t getdns_list_set_int(getdns_list *list, size_t index, uint32_t child_uint32);
590590
591591 /* Dicts: create, destroy, and set the data at a given name */
592592 getdns_dict * getdns_dict_create();
604604 void *(*realloc)(void *userarg, void *, size_t),
605605 void (*free)(void *userarg, void *)
606606 );
607 void getdns_dict_destroy(getdns_dict *this_dict);
608 getdns_return_t getdns_dict_set_dict(getdns_dict *this_dict, const char *name, const getdns_dict *child_dict);
609 getdns_return_t getdns_dict_set_list(getdns_dict *this_dict, const char *name, const getdns_list *child_list);
610 getdns_return_t getdns_dict_set_bindata(getdns_dict *this_dict, const char *name, const getdns_bindata *child_bindata);
611 getdns_return_t getdns_dict_set_int(getdns_dict *this_dict, const char *name, uint32_t child_uint32);
612 getdns_return_t getdns_dict_remove_name(getdns_dict *this_dict, const char *name);
607 void getdns_dict_destroy(getdns_dict *dict);
608 getdns_return_t getdns_dict_set_dict(getdns_dict *dict, const char *name, const getdns_dict *child_dict);
609 getdns_return_t getdns_dict_set_list(getdns_dict *dict, const char *name, const getdns_list *child_list);
610 getdns_return_t getdns_dict_set_bindata(getdns_dict *dict, const char *name, const getdns_bindata *child_bindata);
611 getdns_return_t getdns_dict_set_int(getdns_dict *dict, const char *name, uint32_t child_uint32);
612 getdns_return_t getdns_dict_remove_name(getdns_dict *dict, const char *name);
613613 </div>
614614
615615 <p>Lists are extended with the <code>getdns_list_set_</code> calls with the <code>index</code> set to the
642642
643643 <pre>
644644 /* . . . */
645 getdns_dict * this_extensions = getdns_dict_create();
646 this_ret = getdns_dict_set_int(this_extensions, "dnssec_return_only_secure", GETDNS_EXTENSION_TRUE);
645 getdns_dict * extensions = getdns_dict_create();
646 ret = getdns_dict_set_int(extensions, "dnssec_return_only_secure", GETDNS_EXTENSION_TRUE);
647647 /* . . . Do some processing with the extensions and results . . . */
648648 /* Remember to clean up memory*/
649 getdns_dict_destroy(this_extensions);
649 getdns_dict_destroy(extensions);
650650 </pre>
651651
652652 <p>The extensions described in this section are are:
24252425
24262426 <h1>9. The Generated Files</h1>
24272427
2428 <p>There is <a href="getdns-0.700.tgz">a tarball</a> that includes the .h files,
2428 <p>There is <a href="getdns-0.701.tgz">a tarball</a> that includes the .h files,
24292429 the examples, and so on. The examples all make, even though there is no API implementation, based
24302430 on a pseudo-implementation in the tarball; see make-examples-PLATFORM.sh. Note that this currently builds fine
24312431 on the Macintosh and Ubuntu; help is definitely appreciated on making the build process
+43
-43
src/getdns/getdns.h.in less more
508508
509509 /**
510510 * get the length of the specified list (returned in *answer)
511 * @param this_list list of any of the supported data types
511 * @param list list of any of the supported data types
512512 * @param answer number of valid items in the list
513513 * @return GETDNS_RETURN_GOOD on success
514514 * @return GETDNS_RETURN_NO_SUCH_LIST_ITEM if list is not valid or params are NULL
515515 */
516 getdns_return_t getdns_list_get_length(const getdns_list *this_list,
516 getdns_return_t getdns_list_get_length(const getdns_list *list,
517517 size_t * answer);
518518 /**
519519 * get the enumerated data type of the indexed list item
520 * @param this_list the list from which to fetch the data type
520 * @param list the list from which to fetch the data type
521521 * @param index the item in the list from which to fetch the data type
522522 * @param *answer assigned the value of the data type on success
523523 * @return GETDNS_RETURN_GOOD on success
524524 * @return GETDNS_RETURN_NO_SUCH_LIST_ITEM if the index is out of range or the list is NULL
525525 */
526 getdns_return_t getdns_list_get_data_type(const getdns_list *this_list,
526 getdns_return_t getdns_list_get_data_type(const getdns_list *list,
527527 size_t index, getdns_data_type * answer);
528528 /**
529529 * retrieve the dictionary value of the specified list item, the caller must not free
530530 * storage associated with the return value. When the list is destroyed this
531531 * dict data is also free()'d - keep this in mind when using this function.
532 * @param this_list the list from which to fetch the value
532 * @param list the list from which to fetch the value
533533 * @param index the item in the list from which to fetch the value
534534 * @param **answer assigned a pointer to the dict value of the indexed element
535535 * @return GETDNS_RETURN_GOOD on success
536536 * @return GETDNS_RETURN_NO_SUCH_LIST_ITEM if the index is out of range or the list is NULL
537537 * @return GETDNS_RETURN_WRONG_TYPE_REQUESTED if the data type does not match the contents of the indexed item
538538 */
539 getdns_return_t getdns_list_get_dict(const getdns_list *this_list, size_t index,
539 getdns_return_t getdns_list_get_dict(const getdns_list *list, size_t index,
540540 getdns_dict **answer);
541541
542542 /**
543543 * retrieve the list value of the specified list item, the caller must not free
544544 * storage associated with the return value. When the list is destroyed any
545545 * list data is also free()'d - keep this in mind when using this function.
546 * @param this_list the list from which to fetch the value
546 * @param list the list from which to fetch the value
547547 * @param index the item in the list from which to fetch the value
548548 * @param **answer assigned a pointer to the list value of the indexed element
549549 * @return GETDNS_RETURN_GOOD on success
550550 * @return GETDNS_RETURN_NO_SUCH_LIST_ITEM if the index is out of range or the list is NULL
551551 * @return GETDNS_RETURN_WRONG_TYPE_REQUESTED if the data type does not match the contents of the indexed item
552552 */
553 getdns_return_t getdns_list_get_list(const getdns_list *this_list, size_t index,
553 getdns_return_t getdns_list_get_list(const getdns_list *list, size_t index,
554554 getdns_list **answer);
555555 /**
556556 * retrieve the binary data value of the specified list item, the caller must not
557557 * free storage associated with the return value. When the list is destroyed any
558558 * bindata data is also free()'d - keep this in mind when using this function.
559 * @param this_list the list from which to fetch the value
559 * @param list the list from which to fetch the value
560560 * @param index the item in the list from which to fetch the value
561561 * @param **answer assigned a pointer to the list value of the indexed element
562562 * @return GETDNS_RETURN_GOOD on success
563563 * @return GETDNS_RETURN_NO_SUCH_LIST_ITEM if the index is out of range or the list is NULL
564564 * @return GETDNS_RETURN_WRONG_TYPE_REQUESTED if the data type does not match the contents of the indexed item
565565 */
566 getdns_return_t getdns_list_get_bindata(const getdns_list *this_list, size_t index,
566 getdns_return_t getdns_list_get_bindata(const getdns_list *list, size_t index,
567567 getdns_bindata **answer);
568568 /**
569569 * retrieve the integer value of the specified list item
570 * @param this_list the list from which to fetch the item
570 * @param list the list from which to fetch the item
571571 * @param index the index of the element in the list to fetch from
572572 * @param *answer assigned the integer value of the indexed element
573573 * @return GETDNS_RETURN_GOOD on success
574574 * @return GETDNS_RETURN_NO_SUCH_LIST_ITEM if the index is out of range or the list is NULL
575575 * @return GETDNS_RETURN_WRONG_TYPE_REQUESTED if the data type does not match the contents of the indexed item
576576 */
577 getdns_return_t getdns_list_get_int(const getdns_list *this_list, size_t index,
577 getdns_return_t getdns_list_get_int(const getdns_list *list, size_t index,
578578 uint32_t * answer);
579579
580580 /**
581581 * fetch a list of names from the dictionary, this list must be freed by the caller
582582 * via a call to getdns_list_destroy
583 * @param this_dict dictionary from which to produce the list of names
583 * @param dict dictionary from which to produce the list of names
584584 * @param **answer a pointer to the new list will be assigned to *answer
585585 * @return GETDNS_RETURN_GOOD on success
586586 * @return GETDNS_RETURN_NO_SUCH_DICT_NAME if dict is invalid or empty
587587 */
588 getdns_return_t getdns_dict_get_names(const getdns_dict *this_dict,
588 getdns_return_t getdns_dict_get_names(const getdns_dict *dict,
589589 getdns_list **answer);
590590 /**
591591 * fetch the data type for the data associated with the specified name
592 * @param this_dict dictionary from which to fetch the data type
592 * @param dict dictionary from which to fetch the data type
593593 * @param name a name/key value to look up in the dictionary
594594 * @param *answer data type will be stored at this address
595595 * @return GETDNS_RETURN_GOOD on success
596596 * @return GETDNS_RETURN_NO_SUCH_DICT_NAME if dict is invalid or name does not exist
597597 */
598 getdns_return_t getdns_dict_get_data_type(const getdns_dict *this_dict,
598 getdns_return_t getdns_dict_get_data_type(const getdns_dict *dict,
599599 const char *name, getdns_data_type * answer);
600600 /**
601601 * fetch the dictionary associated with the specified name, the dictionary should
602602 * not be free()'d by the caller, it will be freed when the parent dictionary is
603603 * free()'d
604 * @param this_dict dictionary from which to fetch the dictionary
604 * @param dict dictionary from which to fetch the dictionary
605605 * @param name a name/key value to look up in the dictionary
606606 * @param **answer a copy of the dictionary will be stored at this address
607607 * @return GETDNS_RETURN_GOOD on success
608608 * @return GETDNS_RETURN_NO_SUCH_DICT_NAME if dict is invalid or name does not exist
609609 */
610 getdns_return_t getdns_dict_get_dict(const getdns_dict *this_dict,
610 getdns_return_t getdns_dict_get_dict(const getdns_dict *dict,
611611 const char *name, getdns_dict **answer);
612612 /**
613613 * fetch the list associated with the specified name
614614 * the list should not be free()'d by the caller, when the dictionary is destroyed
615615 * the list will also be destroyed
616 * @param this_dict dictionary from which to fetch the list
616 * @param dict dictionary from which to fetch the list
617617 * @param name a name/key value to look up in the dictionary
618618 * @param **answer a copy of the list will be stored at this address
619619 * @return GETDNS_RETURN_GOOD on success
620620 * @return GETDNS_RETURN_NO_SUCH_DICT_NAME if dict is invalid or name does not exist
621621 */
622 getdns_return_t getdns_dict_get_list(const getdns_dict *this_dict,
622 getdns_return_t getdns_dict_get_list(const getdns_dict *dict,
623623 const char *name, getdns_list **answer);
624624 /**
625625 * fetch the bindata associated with the specified name, the bindata should not be
626626 * free()'d by the caller
627 * @param this_dict dictionary from which to fetch the bindata
627 * @param dict dictionary from which to fetch the bindata
628628 * @param name a name/key value to look up in the dictionary
629629 * @param **answer a copy of the bindata will be stored at this address
630630 * @return GETDNS_RETURN_GOOD on success
631631 * @return GETDNS_RETURN_NO_SUCH_DICT_NAME if dict is invalid or name does not exist
632632 */
633 getdns_return_t getdns_dict_get_bindata(const getdns_dict *this_dict,
633 getdns_return_t getdns_dict_get_bindata(const getdns_dict *dict,
634634 const char *name, getdns_bindata **answer);
635635 /**
636636 * fetch the integer value associated with the specified name
637 * @param this_dict dictionary from which to fetch the integer
637 * @param dict dictionary from which to fetch the integer
638638 * @param name a name/key value to look up in the dictionary
639639 * @param *answer the integer will be stored at this address
640640 * @return GETDNS_RETURN_GOOD on success
641641 * @return GETDNS_RETURN_NO_SUCH_DICT_NAME if dict is invalid or name does not exist
642642 */
643 getdns_return_t getdns_dict_get_int(const getdns_dict *this_dict,
643 getdns_return_t getdns_dict_get_int(const getdns_dict *dict,
644644 const char *name, uint32_t * answer);
645645
646646 /**
668668 * you MUST copy those instances BEFORE you destroy the list else
669669 * unpleasant things will happen at run-time
670670 */
671 void getdns_list_destroy(getdns_list *this_list);
671 void getdns_list_destroy(getdns_list *list);
672672
673673 /**
674674 * assign the child_dict to an item in a parent list, the parent list copies
675675 * the child dict and will free the copy when the list is destroyed
676 * @param this_list list containing the item to which child_list is to be assigned
676 * @param list list containing the item to which child_list is to be assigned
677677 * @param index index of the item within list to which child_list is to be assigned
678678 * @param *child_dict dict to assign to the item
679679 * @return GETDNS_RETURN_GOOD on success
680680 * @return GETDNS_RETURN_NO_SUCH_LIST_ITEM if index is out of range, or list is NULL
681681 */
682 getdns_return_t getdns_list_set_dict(getdns_list *this_list, size_t index,
682 getdns_return_t getdns_list_set_dict(getdns_list *list, size_t index,
683683 const getdns_dict *child_dict);
684684
685685 /**
686686 * assign the child_list to an item in a parent list, the parent list copies
687687 * the child list and will free the copy when the list is destroyed
688 * @param this_list list containing the item to which child_list is to be assigned
688 * @param list list containing the item to which child_list is to be assigned
689689 * @param index index of the item within list to which child_list is to be assigned
690690 * @param *child_list list to assign to the item
691691 * @return GETDNS_RETURN_GOOD on success
692692 * @return GETDNS_RETURN_NO_SUCH_LIST_ITEM if index is out of range, or list is NULL
693693 */
694 getdns_return_t getdns_list_set_list(getdns_list *this_list, size_t index,
694 getdns_return_t getdns_list_set_list(getdns_list *list, size_t index,
695695 const getdns_list *child_list);
696696 /**
697697 * assign the child_bindata to an item in a parent list, the parent list copies
698698 * the child data and will free the copy when the list is destroyed
699 * @param this_list list contiaining the item to which child_list is to be assigned
699 * @param list list contiaining the item to which child_list is to be assigned
700700 * @param index index of the item within list to which child_list is to be assigned
701701 * @param *child_bindata data to assign to the item
702702 * @return GETDNS_RETURN_GOOD on success
703703 * @return GETDNS_RETURN_NO_SUCH_LIST_ITEM if index is out of range, or list is NULL
704704 */
705 getdns_return_t getdns_list_set_bindata(getdns_list *this_list, size_t index,
705 getdns_return_t getdns_list_set_bindata(getdns_list *list, size_t index,
706706 const getdns_bindata *child_bindata);
707707 /**
708708 * set the integer value of the indexed item (zero based index)
709709 * @return GETDNS_RETURN_GOOD on success
710710 * @return GETDNS_RETURN_NO_SUCH_LIST_ITEM if index is out of range, or list is NULL
711711 */
712 getdns_return_t getdns_list_set_int(getdns_list *this_list, size_t index,
712 getdns_return_t getdns_list_set_int(getdns_list *list, size_t index,
713713 uint32_t child_uint32);
714714
715715 /**
735735 * be aware that if you have fetched any data from the dictionary it will
736736 * no longer be available (you are likely to experience bad things if you try)
737737 */
738 void getdns_dict_destroy(getdns_dict *this_dict);
739
740 getdns_return_t getdns_dict_set_dict(getdns_dict *this_dict,
738 void getdns_dict_destroy(getdns_dict *dict);
739
740 getdns_return_t getdns_dict_set_dict(getdns_dict *dict,
741741 const char *name, const getdns_dict *child_dict);
742742 /**
743743 * create a new entry in the dictionary, or replace the value of an existing entry
744744 * this routine makes a copy of the child_list
745 * @param this_dict dictionary in which to add or change the value
745 * @param dict dictionary in which to add or change the value
746746 * @param name key that identifies which item in the dictionary to add/change
747747 * @param child_list value to assign to the node identified by name
748748 * @return GETDNS_RETURN_GOOD on success
749749 */
750 getdns_return_t getdns_dict_set_list(getdns_dict *this_dict,
750 getdns_return_t getdns_dict_set_list(getdns_dict *dict,
751751 const char *name, const getdns_list *child_list);
752752 /**
753753 * create a new entry in the dictionary, or replace the value of an existing entry
754754 * this routine makes a copy of the child_bindata
755 * @param this_dict dictionary in which to add or change the value
755 * @param dict dictionary in which to add or change the value
756756 * @param name key that identifies which item in the dictionary to add/change
757757 * @param child_bindata value to assign to the node identified by name
758758 * @return GETDNS_RETURN_GOOD on success
759759 */
760 getdns_return_t getdns_dict_set_bindata(getdns_dict *this_dict,
760 getdns_return_t getdns_dict_set_bindata(getdns_dict *dict,
761761 const char *name, const getdns_bindata *child_bindata);
762762 /**
763763 * create a new entry in the dictionary, or replace the value of an existing entry
764 * @param this_dict dictionary in which to add or change the value
764 * @param dict dictionary in which to add or change the value
765765 * @param name key that identifies which item in the dictionary to add/change
766766 * @param child_uint32 value to assign to the node identified by name
767767 * @return GETDNS_RETURN_GOOD on success
768768 */
769 getdns_return_t getdns_dict_set_int(getdns_dict *this_dict, const char *name,
769 getdns_return_t getdns_dict_set_int(getdns_dict *dict, const char *name,
770770 uint32_t child_uint32);
771771
772772 /**
773773 * remove the value associated with the specified name
774 * @param this_dict dictionary from which to fetch the integer
774 * @param dict dictionary from which to fetch the integer
775775 * @param name a name/key value to look up in the dictionary
776776 * @return GETDNS_RETURN_GOOD on success
777777 * @return GETDNS_RETURN_NO_SUCH_DICT_NAME if dict is invalid or name does not exist
778778 */
779 getdns_return_t getdns_dict_remove_name(getdns_dict *this_dict, const char *name);
779 getdns_return_t getdns_dict_remove_name(getdns_dict *dict, const char *name);
780780
781781 /* Callback arguments */
782782 typedef void (*getdns_callback_t) (getdns_context *context,