/*   pmfapi.h
* ===========================================================================
*
*                            PUBLIC DOMAIN NOTICE
*            National Center for Biotechnology Information (NCBI)
*
*  This software/database is a "United States Government Work" under the
*  terms of the United States Copyright Act.  It was written as part of
*  the author's official duties as a United States Government employee and
*  thus cannot be copyrighted.  This software/database is freely available
*  to the public for use. The National Library of Medicine and the U.S.
*  Government do not place any restriction on its use or reproduction.
*  We would, however, appreciate having the NCBI and the author cited in
*  any work or product based on this material
*
*  Although all reasonable efforts have been taken to ensure the accuracy
*  and reliability of the software and data, the NLM and the U.S.
*  Government do not and cannot warrant the performance or results that
*  may be obtained by using this software or data. The NLM and the U.S.
*  Government disclaim all warranties, express or implied, including
*  warranties of performance, merchantability or fitness for any particular
*  purpose.
*
* ===========================================================================
*
* File Name:  pmfapi.h
*
* Author:  Jonathan Kans
*
* Version Creation Date:   5/5/00
*
* $Revision: 1.38 $
*
* File Description: 
*
* Modifications:  
* --------------------------------------------------------------------------
*
* ==========================================================================
*/

#ifndef _PMFAPI_
#define _PMFAPI_

#include <ncbi.h>
#include <asn.h>
#include <objmedli.h>
#include <objpubme.h>
#include <objsset.h>
#include <urlquery.h>

#undef NLM_EXTERN
#ifdef NLM_IMPORT
#define NLM_EXTERN NLM_IMPORT
#else
#define NLM_EXTERN extern
#endif


#ifdef __cplusplus
extern "C" {
#endif


/* low-level connection functions */

NLM_EXTERN CONN PubMedFetchOpenConnection (
  Int4 uid
);

NLM_EXTERN CONN PubSeqFetchOpenConnection (
  BIG_ID uid,
  Int2 retcode,
  Int4 flags
);

NLM_EXTERN CONN PubSeqFetchOpenConnectionString (
  CharPtr id,
  Int2 retcode,
  Int4 flags
);

NLM_EXTERN CONN PubSeqFetchTraceOpenConnection (
  Uint4 tid,
  Int2 retcode,
  Int4 flags
);

NLM_EXTERN CONN PubSeqFetchSRAOpenConnection (
  CharPtr sraid
);

NLM_EXTERN CONN GiRevHistOpenConnection (
  BIG_ID uid,
  Int4 num,
  BIG_ID_PNTR uids
);

NLM_EXTERN CONN GiAccVerOpenConnection (
  BIG_ID uid,
  Int4 num,
  BIG_ID_PNTR uids
);

NLM_EXTERN CONN AccnRevHistOpenConnection (
  CharPtr accn
);

NLM_EXTERN CONN GiSeqIdSetOpenConnection (
  BIG_ID gi
);

NLM_EXTERN CONN AccnListOpenConnection (
  CharPtr PNTR accns
);

NLM_EXTERN PubmedEntryPtr PubMedWaitForReply (
  CONN conn
);

NLM_EXTERN SeqEntryPtr PubSeqWaitForReply (
  CONN conn
);

NLM_EXTERN CharPtr GiRevHistWaitForReply (
  CONN conn
);

NLM_EXTERN CharPtr GiAccVerWaitForReply (
  CONN conn
);

NLM_EXTERN BIG_ID AccnRevHistWaitForReply (
  CONN conn
);

NLM_EXTERN SeqIdPtr GiSeqIdSetWaitForReply (
  CONN conn
);

NLM_EXTERN CharPtr AccnListWaitForReply (
  CONN conn
);

/*
 PubMedSynchronousQuery and PubSeqSynchronousQuery open a
 connection, send a uid request, and wait for a reply
*/

NLM_EXTERN PubmedEntryPtr PubMedSynchronousQuery (
  Int4 uid
);

NLM_EXTERN SeqEntryPtr PubSeqSynchronousQueryEx (
  Int4 uid,
  Int2 retcode,
  Int4 flags,
  CharPtr id_str
);

NLM_EXTERN SeqEntryPtr PubSeqSynchronousQuery (
  Int4 uid,
  Int2 retcode,
  Int4 flags
);

NLM_EXTERN SeqEntryPtr PubSeqSynchronousQueryId (
  SeqIdPtr sip,
  Int2 retcode,
  Int4 flags
);

NLM_EXTERN SeqIdPtr SeqIdFromPubSeqString (CharPtr str);

NLM_EXTERN SeqEntryPtr PubSeqSynchronousQueryString (
  CharPtr str,
  Int2 retcode,
  Int4 flags
);

NLM_EXTERN SeqEntryPtr PubSeqSynchronousQueryTI (
  Uint4 tid,
  Int2 retcode,
  Int4 flags
);

NLM_EXTERN SeqEntryPtr PubSeqSynchronousQuerySRA (
  CharPtr sraid
);

NLM_EXTERN CharPtr GiRevHistSynchronousQuery (
  BIG_ID uid,
  Int4 num,
  BIG_ID_PNTR uids
);

NLM_EXTERN CharPtr GiAccVerSynchronousQuery (
  BIG_ID uid,
  Int4 num,
  BIG_ID_PNTR uids
);

NLM_EXTERN BIG_ID AccnRevHistSynchronousQuery (
  CharPtr accn
);

NLM_EXTERN SeqIdPtr GiSeqIdSetSynchronousQuery (
  BIG_ID gi
);

NLM_EXTERN CharPtr AccnListSynchronousQuery (
  CharPtr PNTR accns
);

/*
 PubMedAsynchronousQuery and PubSeqAsynchronousQuery open
 connection, send request, and queue completion routine
 using urlquery queueing mechanism.

 PubMedCheckQueue and PubSeqCheckQueue should be called
 several times a second with a timer.  They each call
 QUERY_CheckQueue to poll connection, which calls completion
 routine when result is available, cleaning up connection
 afterwards.

 PubMedReadReply and PubSeqReadReply take conn and status
 parameters from completion routine and reads PubmedEntryPtr
 or SeqEntryPtr.
*/

NLM_EXTERN Boolean PubMedAsynchronousQuery (
  Int4 uid,
  QUEUE* q,
  QueryResultProc resultproc,
  VoidPtr userdata
);

NLM_EXTERN Int4 PubMedCheckQueue (
  QUEUE* q
);

NLM_EXTERN PubmedEntryPtr PubMedReadReply (
  CONN conn,
  EIO_Status status
);

NLM_EXTERN Boolean PubSeqAsynchronousQuery (
  Int4 uid,
  Int2 retcode,
  Int4 flags,
  QUEUE* q,
  QueryResultProc resultproc,
  VoidPtr userdata
);

NLM_EXTERN Int4 PubSeqCheckQueue (
  QUEUE* q
);

NLM_EXTERN SeqEntryPtr PubSeqReadReply (
  CONN conn,
  EIO_Status status
);

NLM_EXTERN Boolean GiRevHistAsynchronousQuery (
  BIG_ID uid,
  Int4 num,
  BIG_ID_PNTR uids,
  QUEUE* q,
  QueryResultProc resultproc,
  VoidPtr userdata
);

NLM_EXTERN Int4 GiRevHistCheckQueue (
  QUEUE* q
);

NLM_EXTERN CharPtr GiRevHistReadReply (
  CONN conn,
  EIO_Status status
);

NLM_EXTERN Boolean GiAccVerAsynchronousQuery (
  BIG_ID uid,
  Int4 num,
  BIG_ID_PNTR uids,
  QUEUE* q,
  QueryResultProc resultproc,
  VoidPtr userdata
);

NLM_EXTERN Int4 GiAccVerCheckQueue (
  QUEUE* q
);

NLM_EXTERN CharPtr GiAccVerReadReply (
  CONN conn,
  EIO_Status status
);

NLM_EXTERN Boolean AccnRevHistAsynchronousQuery (
  CharPtr accn,
  QUEUE* q,
  QueryResultProc resultproc,
  VoidPtr userdata
);

NLM_EXTERN Int4 AccnRevHistCheckQueue (
  QUEUE* q
);

NLM_EXTERN BIG_ID AccnRevHistReadReply (
  CONN conn,
  EIO_Status status
);

NLM_EXTERN Boolean GiSeqIdSetAsynchronousQuery (
  BIG_ID gi,
  QUEUE* queue,
  QueryResultProc resultproc,
  VoidPtr userdata
);

NLM_EXTERN Int4 GiSeqIdSetCheckQueue (
  QUEUE* queue
);

NLM_EXTERN SeqIdPtr GiSeqIdSetReadReply (
  CONN conn,
  EIO_Status status
);

NLM_EXTERN Boolean AccnListAsynchronousQuery (
  CharPtr PNTR accns,
  QUEUE* queue,
  QueryResultProc resultproc,
  VoidPtr userdata
);

NLM_EXTERN Int4 AccnListCheckQueue (
  QUEUE* queue
);

NLM_EXTERN CharPtr AccnListReadReply (
  CONN conn,
  EIO_Status status
);

/* PMID fetch registration function */

NLM_EXTERN Boolean PubMedFetchEnable (
  void
);

NLM_EXTERN void PubMedFetchDisable (
  void
);

/* SeqId fetch registration function */

NLM_EXTERN Boolean PubSeqFetchEnable (
  void
);

NLM_EXTERN Boolean PubSeqFetchEnableEx (
  Boolean fetch,
  Boolean seqidtogi,
  Boolean gitoseqid,
  Boolean precache,
  Boolean seqidset,
  Int4 flags
);

NLM_EXTERN void PubSeqFetchDisable (
  void
);

/* multiple SeqId preload into cache functions */

NLM_EXTERN Int4 GiRevHistPreLoadSeqIdGiCache (
  Int4 num,
  BIG_ID_PNTR uids
);

NLM_EXTERN Int4 GiRevHistPreLoadSeqIdGiCacheEx (
  Int4 num,
  BIG_ID_PNTR uids,
  Boolean filter
);

NLM_EXTERN Int4 LIBCALLBACK GiRevHistLookupFarSeqIDs (
  SeqEntryPtr sep,
  Boolean components,
  Boolean locations,
  Boolean products,
  Boolean alignments,
  Boolean history,
  Boolean inference,
  Boolean others
);

NLM_EXTERN Int4 AccnListPreLoadSeqIdGiCache (
  CharPtr PNTR accns
);

/* SeqId chain fetch function */

NLM_EXTERN SeqIdPtr LIBCALLBACK GiRevHistLookupSeqIdSet (
  BIG_ID gi
);

/* multiple Accession bulk lookup or preload section */

typedef void (LIBCALLBACK *CacheAccnListProc) (
  BIG_ID gi,
  CharPtr accnver
);

/*
 CacheAccnList takes the AccnList query result, and calls the
 user callback if it is not NULL, otherwise it preloads the
 sequence manager gi/accession lookup cache.  Used internally
 by AccnListPreLoadSeqIdGiCache function.
*/

NLM_EXTERN Int4 CacheAccnList (
  CharPtr str,
  CacheAccnListProc userfunc
);


#ifdef __cplusplus
}
#endif

#undef NLM_EXTERN
#ifdef NLM_EXPORT
#define NLM_EXTERN NLM_EXPORT
#else
#define NLM_EXTERN
#endif

#endif /* _PMFAPI_ */

