<commit_before>/**
 * @file ccn/ccn.h
 *
 * This is the low-level interface for CCNx clients.
 *
 * Part of the CCNx C Library.
 *
 * Copyright (C) 2008-2012 Palo Alto Research Center, Inc.
 *
 * This library is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License version 2.1
 * as published by the Free Software Foundation.
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details. You should have received
 * a copy of the GNU Lesser General Public License along with this library;
 * if not, write to the Free Software Foundation, Inc., 51 Franklin Street,
 * Fifth Floor, Boston, MA 02110-1301 USA.
 */

#ifndef CCN_CCN_DEFINED
#define CCN_CCN_DEFINED

#include <stdint.h>
#include <ccn/coding.h>
#include <ccn/charbuf.h>
#include <ccn/indexbuf.h>

/**
 * A macro that clients may use to cope with an evolving API.
 *
 * The decimal digits of this use the pattern MMVVXXX, where MM is the
 * major release number and VV is the minor version level.
 * XXX will be bumped when an API change is made, but it will not be
 * directly tied to the patch level in a release number.
 * Thus CCN_API_VERSION=1000 would have corresponded to the first public
 * release (0.1.0), but that version did not have this macro defined.
 */
#define CCN_API_VERSION 5001

/**
 * Interest lifetime default.
 *
 * If the interest lifetime is not explicit, this is the default value.
 */
#define CCN_INTEREST_LIFETIME_SEC 4
#define CCN_INTEREST_LIFETIME_MICROSEC (CCN_INTEREST_LIFETIME_SEC * 1000000)

/* opaque declarations */
struct ccn;
struct ccn_pkey;

/* forward declarations */
struct ccn_closure;
struct ccn_upcall_info;
struct ccn_parsed_interest;
struct ccn_parsed_ContentObject;
struct ccn_parsed_Link;

/*
 * Types for implementing upcalls
 * To receive notifications of incoming interests and content, the
 * client creates closures (using client-managed memory).
 */

/**
 * This tells what kind of event the upcall is handling.
 *
 * The KEYMISSING and RAW codes are used only if deferred verification has been
 * requested.
 */
enum ccn_upcall_kind {
    CCN_UPCALL_FINAL,             /**< handler is about to be deregistered */
    CCN_UPCALL_INTEREST,          /**< incoming interest */
    CCN_UPCALL_CONSUMED_INTEREST, /**< incoming interest, someone has answered */
    CCN_UPCALL_CONTENT,           /**< incoming verified content */
    CCN_UPCALL_INTEREST_TIMED_OUT,/**< interest timed out */
    CCN_UPCALL_CONTENT_UNVERIFIED,/**< content that has not been verified */
    CCN_UPCALL_CONTENT_BAD,       /**< verification failed */
    CCN_UPCALL_CONTENT_KEYMISSING,/**< key has not been fetched */
    CCN_UPCALL_CONTENT_RAW        /**< verification has not been attempted */
};

/**
 * Upcalls return one of these values.
 */
enum ccn_upcall_res {
    CCN_UPCALL_RESULT_ERR = -1, /**< upcall detected an error */
    CCN_UPCALL_RESULT_OK = 0,   /**< normal upcall return */
    CCN_UPCALL_RESULT_REEXPRESS = 1, /**< reexpress the same interest again */
    CCN_UPCALL_RESULT_INTEREST_CONSUMED = 2,/**< upcall claims to consume interest */
    CCN_UPCALL_RESULT_VERIFY = 3, /**< force an unverified result to be verified */
    CCN_UPCALL_RESULT_FETCHKEY = 4 /**< request fetching of an unfetched key */
};

/**
 * @type ccn_handler
 * This is the procedure type for the closure's implementation.
 */
typedef enum ccn_upcall_res (*ccn_handler)(
    struct ccn_closure *selfp,
    enum ccn_upcall_kind kind,
    struct ccn_upcall_info *info  /**< details about the event */
);

/**
 * Handle for upcalls that allow clients receive notifications of
 * incoming interests and content.
 * The client is responsible for managing this piece of memory and the
 * data therein. The refcount should be initially zero, and is used by the
 * library to keep to track of multiple registrations of the same closure.
 * When the count drops back to 0, the closure will be called with
 * kind = CCN_UPCALL_FINAL so that it has an opportunity to clean up.
 */
struct ccn_closure {
    ccn_handler p;      /**< client-supplied handler */
    void *data;         /**< for client use */
    intptr_t intdata;   /**< for client use */
    int refcount;       /**< client should not update this directly */
};

/**
 * Additional information provided in the upcall.
 * The client is responsible for managing this piece of memory and the
 * data therein. The refcount should be initially zero, and is used by the
 * library to keep to track of multiple registrations of the same closure.
 * When the count drops back to 0, the closure will be called with
 * kind = CCN_UPCALL_FINAL so that it has an opportunity to clean up.
 */
struct ccn_upcall_info {
    struct ccn *h;              /**< The ccn library handle */
    /* Interest (incoming or matched) */
    const unsigned char *interest_ccnb;
    struct ccn_parsed_interest *pi;
    struct ccn_indexbuf *interest_comps;
    int matched_comps;
    /* Incoming content for CCN_UPCALL_CONTENT* - otherwise NULL */
    const unsigned char *content_ccnb;
    struct ccn_parsed_ContentObject *pco;
    struct ccn_indexbuf *content_comps;
};

/*
 * ccn_create: create a client handle
 * Creates and initializes a client handle, not yet connected.
 * On error, returns NULL and sets errno.
 * Errors: ENOMEM
 */ 
struct ccn *ccn_create(void);

/*
 * ccn_connect: connect to local ccnd
 * Use NULL for name to get the default.
 * Normal return value is the fd for the connection.
 * On error, returns -1.
 */ 
int ccn_connect(struct ccn *h, const char *name);

/*
 * ccn_get_connection_fd: get connection socket fd
 * This is in case the client needs to know the associated
 * file descriptor, e.g. for use in select/poll.
 * The client should not use this fd for actual I/O.
 * Normal return value is the fd for the connection.
 * Returns -1 if the handle is not connected.
 */ 
int ccn_get_connection_fd(struct ccn *h);

/*
 * ccn_disconnect: disconnect from local ccnd
 * This breaks the connection and discards buffered I/O,
 * but leaves other state intact.
 */ 
int ccn_disconnect(struct ccn *h);

/*
 * ccn_destroy: destroy handle
 * Releases all resources associated with *hp and sets it to NULL.
 */ 
void ccn_destroy(struct ccn **hp);

/* Control where verification happens */
int ccn_defer_verification(struct ccn *h, int defer);

/***********************************
 * Writing Names
 * Names for interests are constructed in charbufs using 
 * the following routines.
 */

/*
 * ccn_name_init: reset charbuf to represent an empty Name in binary format
 * Return value is 0, or -1 for error.
 */
int ccn_name_init(struct ccn_charbuf *c);

/*
 * ccn_name_append: add a Component to a Name
 * The component is an arbitrary string of n octets, no escaping required.
 * Return value is 0, or -1 for error.
 */
int ccn_name_append(struct ccn_charbuf *c, const void *component, size_t n);

/*
 * ccn_name_append_str: add a Component that is a \0 terminated string.
 * The component added is the bytes of the string without the \0.
 * This function is convenient for those applications that construct 
 * component names from simple strings.
 * Return value is 0, or -1 for error
 */
int ccn_name_append_str(struct ccn_charbuf *c, const char *s);

/*
 * ccn_name_append_components: add sequence of ccnb-encoded Components
 *    to a ccnb-encoded Name
 * start and stop are offsets from ccnb
 * Return value is 0, or -1 for obvious error
 */
int ccn_name_append_components(struct ccn_charbuf *c,
                               const unsigned char *ccnb,
                               size_t start, size_t stop);

enum ccn_marker {
    CCN_MARKER_NONE = -1,
    CCN_MARKER_SEQNUM  = 0x00, /**< consecutive block sequence numbers */
    CCN_MARKER_CONTROL = 0xC1, /**< commands, etc. */ 
    CCN_MARKER_OSEQNUM = 0xF8, /**< deprecated */
    CCN_MARKER_BLKID   = 0xFB, /**< nonconsecutive block ids */
    CCN_MARKER_VERSION = 0xFD  /**< timestamp-based versioning */
};

/*
 * ccn_name_append_numeric: add binary Component to ccnb-encoded Name
 * These are special components used for marking versions, fragments, etc.
 * Return value is 0, or -1 for error
 * see doc/technical/NameConventions.html
 */
int ccn_name_append_numeric(struct ccn_charbuf *c,
                            enum ccn_marker tag, uintmax_t value);

/*
 * ccn_name_append_nonce: add nonce Component to ccnb-encoded Name
 * Uses %C1.N.n marker.
 * see doc/technical/NameConventions.html
 */
int ccn_name_append_nonce(struct ccn_charbuf *c);

/*
 * ccn_name_split: find Component boundaries in a ccnb-encoded Name
 * Thin veneer over ccn_parse_Name().
 * returns -1 for error, otherwise the number of Components
 * components arg may be NULL to just do a validity check
 */
int ccn_name_split(const struct ccn_charbuf *c,
                   struct ccn_indexbuf* components);

/*
 * ccn_name_chop: Chop the name down to n components.
 * returns -1 for error, otherwise the new number of Components
 * components arg may be NULL; if provided it must be consistent with
 * some prefix of the name, and is updated accordingly.
 * n may be negative to say how many components to remove instead of how
 * many to leave, e.g. -1 will remove just the last component.
 */
int ccn_name_chop(struct ccn_charbuf *c,
                  struct ccn_indexbuf* components, int n);


/***********************************
 * Authenticators and signatures for content are constructed in charbufs
 * using the following routines.
 */

enum ccn_content_type {
    CCN_CONTENT_DATA = 0x0C04C0,
    CCN_CONTENT_ENCR = 0x10D091,
    CCN_CONTENT_GONE = 0x18E344,
    CCN_CONTENT_KEY  = <KEY>,
    CCN_CONTENT_LINK = 0x2C834A,
    CCN_CONTENT_NACK = 0x34008A
};

/***********************************
 * ccn_express_interest: 
 * Use the above routines to set up namebuf.
 * Matching occurs only on the first prefix_comps components of
 * the name, or on all components if prefix_comps is -1.
 * Any remaining components serve to establish the starting point for
 * the search for matching content.
 * The namebuf may be reused or destroyed after the call.
 * If action is not NULL, it is invoked when matching data comes back.
 * If interest_template is supplied, it should contain a ccnb formatted
 * interest message to provide the other portions of the interest.
 * It may also be reused or destroyed after the call.
 * When an interest times out, the upcall may return
 * CCN_UPCALL_RESULT_REEXPRESS to simply re-express the interest.
 * The default is to unregister the handler.  The common use will be for
 * the upcall to register again with an interest modified to prevent matching
 * the same interest again.
 */
int ccn_express_interest(struct ccn *h,
                         struct ccn_charbuf *namebuf,
                         struct ccn_closure *action,
                         struct ccn_charbuf *interest_template);

/***********************************
 * ccn_set_interest_filter: 
 * The action, if provided, will be called when an interest arrives that
 * has the given name as a prefix.
 * If action is NULL, any existing filter is removed.
 * The namebuf may be reused or destroyed after the call.
 * Handler should return CCN_UPCALL_RESULT_ERR if it cannot matching content.
 * The upcall kind passed to the handler will be CCN_UPCALL_INTEREST
 * if no other handler has claimed to produce content, or else
 * CCN_UPCALL_CONSUMED_INTEREST.
 */
int ccn_set_interest_filter(struct ccn *h, struct ccn_charbuf *namebuf,
                            struct ccn_closure *action);

/*
 * Variation allows non-default forwarding flags.
 */
int ccn_set_interest_filter_with_flags(struct ccn *h,
                                       struct ccn_charbuf *namebuf,
                                       struct ccn_closure *action,<commit_msg>refs #100676  Simplify the comments around ccn_set_interest_filter in the header file<commit_after>/**
 * @file ccn/ccn.h
 *
 * This is the low-level interface for CCNx clients.
 *
 * Part of the CCNx C Library.
 *
 * Copyright (C) 2008-2012 Palo Alto Research Center, Inc.
 *
 * This library is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License version 2.1
 * as published by the Free Software Foundation.
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details. You should have received
 * a copy of the GNU Lesser General Public License along with this library;
 * if not, write to the Free Software Foundation, Inc., 51 Franklin Street,
 * Fifth Floor, Boston, MA 02110-1301 USA.
 */

#ifndef CCN_CCN_DEFINED
#define CCN_CCN_DEFINED

#include <stdint.h>
#include <ccn/coding.h>
#include <ccn/charbuf.h>
#include <ccn/indexbuf.h>

/**
 * A macro that clients may use to cope with an evolving API.
 *
 * The decimal digits of this use the pattern MMVVXXX, where MM is the
 * major release number and VV is the minor version level.
 * XXX will be bumped when an API change is made, but it will not be
 * directly tied to the patch level in a release number.
 * Thus CCN_API_VERSION=1000 would have corresponded to the first public
 * release (0.1.0), but that version did not have this macro defined.
 */
#define CCN_API_VERSION 5001

/**
 * Interest lifetime default.
 *
 * If the interest lifetime is not explicit, this is the default value.
 */
#define CCN_INTEREST_LIFETIME_SEC 4
#define CCN_INTEREST_LIFETIME_MICROSEC (CCN_INTEREST_LIFETIME_SEC * 1000000)

/* opaque declarations */
struct ccn;
struct ccn_pkey;

/* forward declarations */
struct ccn_closure;
struct ccn_upcall_info;
struct ccn_parsed_interest;
struct ccn_parsed_ContentObject;
struct ccn_parsed_Link;

/*
 * Types for implementing upcalls
 * To receive notifications of incoming interests and content, the
 * client creates closures (using client-managed memory).
 */

/**
 * This tells what kind of event the upcall is handling.
 *
 * The KEYMISSING and RAW codes are used only if deferred verification has been
 * requested.
 */
enum ccn_upcall_kind {
    CCN_UPCALL_FINAL,             /**< handler is about to be deregistered */
    CCN_UPCALL_INTEREST,          /**< incoming interest */
    CCN_UPCALL_CONSUMED_INTEREST, /**< incoming interest, someone has answered */
    CCN_UPCALL_CONTENT,           /**< incoming verified content */
    CCN_UPCALL_INTEREST_TIMED_OUT,/**< interest timed out */
    CCN_UPCALL_CONTENT_UNVERIFIED,/**< content that has not been verified */
    CCN_UPCALL_CONTENT_BAD,       /**< verification failed */
    CCN_UPCALL_CONTENT_KEYMISSING,/**< key has not been fetched */
    CCN_UPCALL_CONTENT_RAW        /**< verification has not been attempted */
};

/**
 * Upcalls return one of these values.
 */
enum ccn_upcall_res {
    CCN_UPCALL_RESULT_ERR = -1, /**< upcall detected an error */
    CCN_UPCALL_RESULT_OK = 0,   /**< normal upcall return */
    CCN_UPCALL_RESULT_REEXPRESS = 1, /**< reexpress the same interest again */
    CCN_UPCALL_RESULT_INTEREST_CONSUMED = 2,/**< upcall claims to consume interest */
    CCN_UPCALL_RESULT_VERIFY = 3, /**< force an unverified result to be verified */
    CCN_UPCALL_RESULT_FETCHKEY = 4 /**< request fetching of an unfetched key */
};

/**
 * @type ccn_handler
 * This is the procedure type for the closure's implementation.
 */
typedef enum ccn_upcall_res (*ccn_handler)(
    struct ccn_closure *selfp,
    enum ccn_upcall_kind kind,
    struct ccn_upcall_info *info  /**< details about the event */
);

/**
 * Handle for upcalls that allow clients receive notifications of
 * incoming interests and content.
 *
 * The client is responsible for managing this piece of memory and the
 * data therein. The refcount should be initially zero, and is used by the
 * library to keep to track of multiple registrations of the same closure.
 * When the count drops back to 0, the closure will be called with
 * kind = CCN_UPCALL_FINAL so that it has an opportunity to clean up.
 */
struct ccn_closure {
    ccn_handler p;      /**< client-supplied handler */
    void *data;         /**< for client use */
    intptr_t intdata;   /**< for client use */
    int refcount;       /**< client should not update this directly */
};

/**
 * Additional information provided in the upcall.
 *
 * The client is responsible for managing this piece of memory and the
 * data therein. The refcount should be initially zero, and is used by the
 * library to keep to track of multiple registrations of the same closure.
 * When the count drops back to 0, the closure will be called with
 * kind = CCN_UPCALL_FINAL so that it has an opportunity to clean up.
 */
struct ccn_upcall_info {
    struct ccn *h;              /**< The ccn library handle */
    /* Interest (incoming or matched) */
    const unsigned char *interest_ccnb;
    struct ccn_parsed_interest *pi;
    struct ccn_indexbuf *interest_comps;
    int matched_comps;
    /* Incoming content for CCN_UPCALL_CONTENT* - otherwise NULL */
    const unsigned char *content_ccnb;
    struct ccn_parsed_ContentObject *pco;
    struct ccn_indexbuf *content_comps;
};

/*
 * ccn_create: create a client handle
 * Creates and initializes a client handle, not yet connected.
 * On error, returns NULL and sets errno.
 * Errors: ENOMEM
 */ 
struct ccn *ccn_create(void);

/*
 * ccn_connect: connect to local ccnd
 * Use NULL for name to get the default.
 * Normal return value is the fd for the connection.
 * On error, returns -1.
 */ 
int ccn_connect(struct ccn *h, const char *name);

/*
 * ccn_get_connection_fd: get connection socket fd
 * This is in case the client needs to know the associated
 * file descriptor, e.g. for use in select/poll.
 * The client should not use this fd for actual I/O.
 * Normal return value is the fd for the connection.
 * Returns -1 if the handle is not connected.
 */ 
int ccn_get_connection_fd(struct ccn *h);

/*
 * ccn_disconnect: disconnect from local ccnd
 * This breaks the connection and discards buffered I/O,
 * but leaves other state intact.
 */ 
int ccn_disconnect(struct ccn *h);

/*
 * ccn_destroy: destroy handle
 * Releases all resources associated with *hp and sets it to NULL.
 */ 
void ccn_destroy(struct ccn **hp);

/* Control where verification happens */
int ccn_defer_verification(struct ccn *h, int defer);

/***********************************
 * Writing Names
 * Names for interests are constructed in charbufs using 
 * the following routines.
 */

/*
 * ccn_name_init: reset charbuf to represent an empty Name in binary format
 * Return value is 0, or -1 for error.
 */
int ccn_name_init(struct ccn_charbuf *c);

/*
 * ccn_name_append: add a Component to a Name
 * The component is an arbitrary string of n octets, no escaping required.
 * Return value is 0, or -1 for error.
 */
int ccn_name_append(struct ccn_charbuf *c, const void *component, size_t n);

/*
 * ccn_name_append_str: add a Component that is a \0 terminated string.
 * The component added is the bytes of the string without the \0.
 * This function is convenient for those applications that construct 
 * component names from simple strings.
 * Return value is 0, or -1 for error
 */
int ccn_name_append_str(struct ccn_charbuf *c, const char *s);

/*
 * ccn_name_append_components: add sequence of ccnb-encoded Components
 *    to a ccnb-encoded Name
 * start and stop are offsets from ccnb
 * Return value is 0, or -1 for obvious error
 */
int ccn_name_append_components(struct ccn_charbuf *c,
                               const unsigned char *ccnb,
                               size_t start, size_t stop);

enum ccn_marker {
    CCN_MARKER_NONE = -1,
    CCN_MARKER_SEQNUM  = 0x00, /**< consecutive block sequence numbers */
    CCN_MARKER_CONTROL = 0xC1, /**< commands, etc. */ 
    CCN_MARKER_OSEQNUM = 0xF8, /**< deprecated */
    CCN_MARKER_BLKID   = 0xFB, /**< nonconsecutive block ids */
    CCN_MARKER_VERSION = 0xFD  /**< timestamp-based versioning */
};

/*
 * ccn_name_append_numeric: add binary Component to ccnb-encoded Name
 * These are special components used for marking versions, fragments, etc.
 * Return value is 0, or -1 for error
 * see doc/technical/NameConventions.html
 */
int ccn_name_append_numeric(struct ccn_charbuf *c,
                            enum ccn_marker tag, uintmax_t value);

/*
 * ccn_name_append_nonce: add nonce Component to ccnb-encoded Name
 * Uses %C1.N.n marker.
 * see doc/technical/NameConventions.html
 */
int ccn_name_append_nonce(struct ccn_charbuf *c);

/*
 * ccn_name_split: find Component boundaries in a ccnb-encoded Name
 * Thin veneer over ccn_parse_Name().
 * returns -1 for error, otherwise the number of Components
 * components arg may be NULL to just do a validity check
 */
int ccn_name_split(const struct ccn_charbuf *c,
                   struct ccn_indexbuf* components);

/*
 * ccn_name_chop: Chop the name down to n components.
 * returns -1 for error, otherwise the new number of Components
 * components arg may be NULL; if provided it must be consistent with
 * some prefix of the name, and is updated accordingly.
 * n may be negative to say how many components to remove instead of how
 * many to leave, e.g. -1 will remove just the last component.
 */
int ccn_name_chop(struct ccn_charbuf *c,
                  struct ccn_indexbuf* components, int n);


/***********************************
 * Authenticators and signatures for content are constructed in charbufs
 * using the following routines.
 */

enum ccn_content_type {
    CCN_CONTENT_DATA = 0x0C04C0,
    CCN_CONTENT_ENCR = 0x10D091,
    CCN_CONTENT_GONE = 0x18E344,
    CCN_CONTENT_KEY  = <KEY>,
    CCN_CONTENT_LINK = 0x2C834A,
    CCN_CONTENT_NACK = 0x34008A
};

/***********************************
 * ccn_express_interest: 
 * Use the above routines to set up namebuf.
 * Matching occurs only on the first prefix_comps components of
 * the name, or on all components if prefix_comps is -1.
 * Any remaining components serve to establish the starting point for
 * the search for matching content.
 * The namebuf may be reused or destroyed after the call.
 * If action is not NULL, it is invoked when matching data comes back.
 * If interest_template is supplied, it should contain a ccnb formatted
 * interest message to provide the other portions of the interest.
 * It may also be reused or destroyed after the call.
 * When an interest times out, the upcall may return
 * CCN_UPCALL_RESULT_REEXPRESS to simply re-express the interest.
 * The default is to unregister the handler.  The common use will be for
 * the upcall to register again with an interest modified to prevent matching
 * the same interest again.
 */
int ccn_express_interest(struct ccn *h,
                         struct ccn_charbuf *namebuf,
                         struct ccn_closure *action,
                         struct ccn_charbuf *interest_template);

/*
 * Register to receive interests on a prefix
 */
int ccn_set_interest_filter(struct ccn *h, struct ccn_charbuf *namebuf,
                            struct ccn_closure *action);

/*
 * Variation allows non-default forwarding flags
 */
int ccn_set_interest_filter_with_flags(struct ccn *h,
                                       struct ccn_charbuf *namebuf,
                                       struct ccn_closure *action,
{'fraction_non_alphanumeric': 0.08206042090970808, 'fraction_numerical': 0.009164969450101833, 'mean_word_length': 3.375974749350167, 'pattern_counts': {'":': 0, '<': 65, '<?xml version=': 0, '>': 13, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2093582', 'n_tokens_mistral': 7111, 'n_tokens_neox': 6871, 'n_words': 2807}