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, the "year" in $(time.year)               */
   int  nWidth;      /* rendered field width (zero-padded); 0 = variable    */
   int  nMin;        /* smallest valid value; names outside nMin..nMax are  */
   int  nMax;        /* skipped with a warning                               */
} 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, defined in uri.c.  A level is one path component: a directory name
 * or the file name. */
typedef struct das_uri_seg_t DasUriSeg;
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 directory above the first variable        */
                           /* component, no trailing separator; "." when the  */
                           /* template is relative, "/" when only the root    */
                           /* is fixed                                        */
   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()    */
   void*             pState;         /* scan state, owned by the iterator    */
} 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_ */