uri.h

Go to the documentation of this file.

/* Copyright (C) 2026 Chris Piker <chris-piker@uiowa.edu>
 *
 * This file is part of das2C, the Core Das2 C Library.
 *
 * das2C 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.
 *
 * das2C 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
 * version 2.1 along with das2C; if not, see <http://www.gnu.org/licenses/>.
 */
 
#ifndef _das_uri_h_
#define _das_uri_h_
 
#include <stdbool.h>
#include <stdint.h>
 
#include <das3/defs.h>
#include <das3/time.h>
#include <das3/datum.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
 
/* ************************************************************************* */
/* Limits */
 
#define DURI_MAX_PATH  2048
 
 
/* ************************************************************************* */
/* Coordinate segment field and type definitions */
 
typedef struct das_uri_field_t {
   char cShort;      /* single-char short token, e.g. 'Y'; '\0' if none     */
   char sLong[32];   /* long name used in qualified tokens, e.g. "year" in $(time.year) */
   int  nWidth;      /* rendered field width (zero-padded); 0 = variable    */
   int  nMin;        /* valid decoded-value range, minimum (inclusive)       */
   int  nMax;        /* valid decoded-value range, maximum (inclusive)       */
} DasUriField;
 
 
typedef struct das_uri_seg_def_t {
   char         sCoord[32]; /* coordinate name, e.g. "time", "sclk", "orbit" */
   int          nFields;    /* number of entries in pFields                   */
   DasUriField* pFields;    /* sub-field table; caller owns until register()  */
} DasUriSegDef;
 
 
/* ************************************************************************* */
/* Coordinate query range */
 
typedef struct das_range_t {
   char      sCoord[32]; /* coordinate or sub-field: "time", "sclk.mod64k"  */
   das_datum dBeg;       /* inclusive range begin                             */
   das_datum dEnd;       /* exclusive range end                               */
} das_range;
 
 
/* ************************************************************************* */
/* Range initializers */
 
DAS_API DasErrCode das_range_fromUtc(
   das_range* pRng, const char* sBeg, const char* sEnd
);
 
 
DAS_API DasErrCode das_range_fromTime(
   das_range* pRng, const das_time* tBeg, const das_time* tEnd
);
 
 
DAS_API DasErrCode das_range_fromInt(
   das_range* pRng, const char* sCoord, int64_t nBeg, int64_t nEnd
);
 
 
DAS_API DasErrCode das_range_fromDatum(
   das_range* pRng, const char* sCoord,
   const das_datum* dmBeg, const das_datum* dmEnd
);
 
 
/* ************************************************************************* */
/* Protocol enumeration */
 
typedef enum das_uri_proto_e {
   DURI_PROTO_FILE  = 0, /* no prefix, or explicit file://                    */
   DURI_PROTO_HTTP,      /* http://                                            */
   DURI_PROTO_HTTPS,     /* https://                                           */
} DasUriProto;
 
 
/* Opaque segment type — full definition in uri.c */
typedef struct das_uri_seg_t DasUriSeg;
 
/* Opaque level plan type — full definition in uri.c.
 * A "level" is one path component (one directory name, or the filename).
 * The plan is built from pSegs at DasUriTplt_pattern() time and is read-only
 * thereafter; iterators hold only runtime directory-walk state, not plan state. */
typedef struct das_uri_level_t DasUriLevel;
 
 
/* ************************************************************************* */
/* A parsed URI template */
 
typedef struct das_uri_tplt_t {
   bool         bHasWild;  /* true if template contains $x or $v             */
   bool         bLiteral;  /* true if template contains no coordinate fields; */
                           /* ranges are ignored and one path is yielded      */
   DasUriProto  eProto;    /* protocol derived from leading scheme, or        */
                           /* DURI_PROTO_FILE if no prefix is present         */
   int          nSegs;     /* number of entries in pSegs                      */
   DasUriSeg*   pSegs;     /* heap-allocated segment array; freed by del_     */
   int          nDefs;     /* number of registered coordinate definitions     */
   DasUriSegDef* pDefs;    /* deep-copied def array; freed by del_            */
   char*        sBase;     /* fixed path prefix up to the first variable;     */
                           /* "." for CWD-relative templates; root ("/" on    */
                           /* POSIX, "C:\\" on Windows) if only the root is   */
                           /* fixed.  No trailing separator otherwise.        */
   int          nLevels;   /* number of directory + filename levels           */
   DasUriLevel* pLevels;   /* level plan built in DasUriTplt_pattern();       */
                           /* freed by del_DasUriTplt()                       */
} DasUriTplt;
 
 
/* ************************************************************************* */
/* A streaming iterator over a URI template and coordinate ranges */
 
typedef struct das_uri_iter_t {
   const DasUriTplt* pTplt;
   int               nRanges;
   const das_range*  pRanges;        /* caller owns; must outlive iterator   */
   bool              bDone;
   char              sCurrent[DURI_MAX_PATH]; /* path returned by _next()    */
                    /* For file:// the file:// prefix is stripped; the path  */
                    /* is usable directly with fopen() etc.                  */
                    /* For http/https the full URL is stored here; the caller*/
                    /* is responsible for downloading before use.            */
   void*             pState;         /* internal heap-allocated scan state;  */
                                     /* managed by init_/fini_/new_/del_     */
} DasUriIter;
 
 
/* ************************************************************************* */
/* API */
 
DAS_API const DasUriSegDef* das_time_uridef(void);
 
 
DAS_API DasUriTplt* new_DasUriTplt(void);
 
 
DAS_API DasErrCode DasUriTplt_register(DasUriTplt* pThis, const DasUriSegDef* pDef);
 
 
DAS_API DasErrCode DasUriTplt_pattern(DasUriTplt* pThis, const char* sTemplate);
 
 
DAS_API void del_DasUriTplt(DasUriTplt* pTplt);
 
 
DAS_API char* DasUriTplt_toStr(const DasUriTplt* pThis, char* sBuf, int nLen);
 
 
DAS_API DasErrCode init_DasUriIter(
   DasUriIter* pThis, const DasUriTplt* pTplt,
   int nRanges, const das_range* pRanges
);
 
 
DAS_API void fini_DasUriIter(DasUriIter* pThis);
 
 
DAS_API DasUriIter* new_DasUriIter(
   const DasUriTplt* pTplt, int nRanges, const das_range* pRanges
);
 
 
DAS_API const char* DasUriIter_next(DasUriIter* pThis);
 
 
DAS_API void del_DasUriIter(DasUriIter* pThis);
 
 
/* ************************************************************************* */
/* Convenience functions */
 
DAS_API char* DasUriTplt_render(
   const DasUriTplt* pThis, int nRanges, const das_range* pRanges,
   char* sBuf, int nLen
);
 
 
DAS_API char** das_uri_list(
   const char* sTemplate, const DasUriSegDef* pDef,
   int nRanges, const das_range* pRanges,
   size_t* pCount
);
 
 
#ifdef __cplusplus
}
#endif
 
#endif /* _das_uri_h_ */