/*
      This file is part of GNUnet
      (C)

      GNUnet is free software; you can redistribute it and/or modify
      it under the terms of the GNU General Public License as published
      by the Free Software Foundation; either version 2, or (at your
      option) any later version.

      GNUnet 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
      General Public License for more details.

      You should have received a copy of the GNU General Public License
      along with GNUnet; see the file COPYING.  If not, write to the
      Free Software Foundation, Inc., 59 Temple Place - Suite 330,
      Boston, MA 02111-1307, USA.
 */

/**
 * @file include/gnunet_datasearch_service.h
 * @brief API to the distributed HTTP datasearch service
 * @author Christian Grothoff
 */
#ifndef GNUNET_DATASEARCH_SERVICE_H
#define GNUNET_DATASEARCH_SERVICE_H

#ifdef __cplusplus
extern "C"
{
#if 0                           /* keep Emacsens' auto-indent happy */
}
#endif
#endif

/**
 * Version of the datasearch API.
 */
#define GNUNET_DATASEARCH_VERSION 0x00000000


/**
 * Opaque handle.
 */
struct GNUNET_DatasearchHandle;

struct GNUNET_DATASEARCH_QueryHandle;
/**
 * Connect to datasearch service.
 *
 * @param cfg configuration to use
 * @param uh url handler to call
 * @param uh_cls closure for uh
 * @return NULL on error
 */
struct GNUNET_DatasearchHandle *
GNUNET_DATASEARCH_connect (struct GNUNET_CONFIGURATION_Handle *cfg);


/**
 * Add the given URL and plaintext to the index.
 *
 * @param h service handle
 * @param url URL to add
 * @param links NULL-terminated array of links found at the URL
 * @param plaintext full text recovered from the url]
 * @param access_time time of the access
 */
void
GNUNET_DATASEARCH_add (struct GNUNET_DatasearchHandle *h,
		       const char *url,
		       const char **links,
		       const char *plaintext,
		       struct GNUNET_TIME_Absolute access_time);


/**
 * Function called for each result found.
 *
 * @param cls closure
 * @param url url of the result
 * @param access_time time the URL was accessed
 */
typedef void (*GNUNET_DATASEARCH_ResultProcessor)(void *cls,
						  const char *url,
						  struct GNUNET_TIME_Absolute access_time);


/**
 *  Search the database for matches to a particular URL
 *
 * @param h service handle
 * @param url to query (must match exactly)
 * @param proc function to call with result
 * @param proc_cls closure for proc
 */
struct GNUNET_DATASEARCH_QueryHandle *
GNUNET_DATASEARCH_query_url (struct GNUNET_DatasearchHandle *h,
			     const char *url,
			     GNUNET_DATASEARCH_ResultProcessor proc,
			     void *proc_cls);


/**
 *  Search the database for matches to a particular query.
 *
 * @param h service handle
 * @param query search string
 * @param proc function to call with result
 * @param proc_cls closure for proc
 */
struct GNUNET_DATASEARCH_QueryHandle *
GNUNET_DATASEARCH_query (struct GNUNET_DatasearchHandle *h,
			 const char *query,
			 GNUNET_DATASEARCH_ResultProcessor proc,
			 void *proc_cls);


/**
 * Search the database for other sites linking to a particular URL.
 *
 * @param h service handle
 * @param url for which we care about sites linking to
 * @param proc function to call with result
 * @param proc_cls closure for proc
 */
struct GNUNET_DATASEARCH_QueryHandle *
GNUNET_DATASEARCH_query_links (struct GNUNET_DatasearchHandle *h,
			       const char *url,
			       GNUNET_DATASEARCH_ResultProcessor proc,
			       void *proc_cls);
/**
 * Notify the service we don't want any result more
 *
 * @param query_handle query to stop
 */

void
GNUNET_DATASHEARCH_query_stop (struct GNUNET_DATASEARCH_QueryHandle *query_handle);

/**
 * Disconnect from the service
 *
 * @param h service handle
 */
void
GNUNET_DATASEARCH_disconnect (struct GNUNET_DatasearchHandle *h);


#if 0                           /* keep Emacsens' auto-indent happy */
{
#endif
#ifdef __cplusplus
}
#endif

#endif