URN Server API v1
Not logged in

Private Procedure "hasPerms" (from "common.tcl")

    Required argument "name"

This TH1 procedure returns non-zero if the logged-in user has the
specified named permission -OR- the server has been configured in
such a way to permit anybody to have it, e.g. any user may lookup
packages.



Private Procedure "emitFormStart" (from "common.tcl")

    Required argument "name"
    Required argument "title"

This TH1 procedure emits the necessary HTML to start a <FORM> element
suitable for use with Fossil and optionally having a title to be used
as header text. The name must not contain any characters reserved in
HTML; however, the title will be properly escaped.



Private Procedure "emitHidden" (from "common.tcl")

    Required argument "name"
    Required argument "value"

This TH1 procedure emits the necessary HTML for a hidden form element
that has a name and value. The name must not contain any characters
reserved in HTML; however, the value will be properly escaped.



Private Procedure "emitTextBox" (from "common.tcl")

    Required argument "name"
    Required argument "value"
    Required argument "size"

This TH1 procedure emits the necessary HTML for a text box form element
that has a name, value, and size. The name and size must not contain
any characters reserved in HTML; however, the value will be properly
escaped.



Private Procedure "emitTextArea" (from "common.tcl")

    Required argument "name"
    Required argument "value"
    Required argument "rows"
    Required argument "columns"

This TH1 procedure emits the necessary HTML for a text area form
element that has a name, value, rows, and columns. The name, rows,
and columns must not contain any characters reserved in HTML; however,
the value will be properly escaped.



Private Procedure "emitCheckBox" (from "common.tcl")

    Required argument "name"
    Required argument "value"

This TH1 procedure emits the necessary HTML for a check box form
element that has a name and value. The name must not contain any
characters reserved in HTML; however, the value will be properly
escaped.



Private Procedure "emitSubmitButton" (from "common.tcl")

    Required argument "name"
    Required argument "value"

This TH1 procedure emits the necessary HTML for a submit button form
element that has a name and value. The name must not contain any
characters reserved in HTML; however, the value will be properly
escaped.



Private Procedure "emitFormEnd" (from "common.tcl")

This TH1 procedure emits the necessary HTML to end a <FORM> element
suitable for use with Fossil. There are no arguments.



Private Procedure "sql_function_regexp" (from "common.tcl")

    Optional argument list "args"

This Tcl procedure is used to implement a SQL function for SQLite.
It implements the REGEXP function (and its associated operator) by
using the Tcl [regexp] command.



Private Procedure "isValidApiKey" (from "common.tcl")

    Required argument "value"
    Optional argument "writing" with default value "false"
    Optional argument "emptyOk" with default value "false"

This Tcl procedure returns non-zero if the specified string value is
a valid API key. An API key has no relationship to a Fossil check-in
hash, even though it may look like one. The emptyOk argument can be
non-zero if the caller wishes to permit an empty string.



Private Procedure "isValidOwnerName" (from "common.tcl")

    Required argument "value"
    Optional argument "emptyOk" with default value "false"

This Tcl procedure returns non-zero if the specified string value is
suitable for use as an owner (entity) name. Only the Latin alphabet
and the space character are allowed.



Private Procedure "isValidMessage" (from "common.tcl")

    Required argument "value"
    Optional argument "emptyOk" with default value "false"

This Tcl procedure returns non-zero if the specified string value is
a valid (log) message. It must be valid Base64 data and the encoded
length is limited to 256K. Therefore, the unencoded length limit is
about 192K.



Private Procedure "isValidScriptName" (from "common.tcl")

    Required argument "value"
    Optional argument "emptyOk" with default value "false"

This Tcl procedure returns non-zero if the specified string value is
a valid script name. The emptyOk argument can be non-zero if the
caller wishes to permit an empty string.



Private Procedure "isValidGuid" (from "common.tcl")

    Required argument "value"
    Optional argument "emptyOk" with default value "false"

This Tcl procedure returns non-zero if the specified string value
is a valid GUID string. The emptyOk argument can be non-zero if
the caller wishes to permit an empty string.



Private Procedure "isValidHash" (from "common.tcl")

    Required argument "value"
    Optional argument "emptyOk" with default value "false"

This Tcl procedure returns non-zero if the specified string value is
a valid SHA1 hash. This has no relationship to a Fossil check-in
hash, even though it may look like one. The emptyOk argument can be
non-zero if the caller wishes to permit an empty string.



Private Procedure "verifyMessageAgainstHash" (from "common.tcl")

    Required argument "hmacKey"
    Required argument "message"
    Required argument "hash"

This Tcl procedure returns non-zero if the specified message string,
which must be Base64 encoded, validates based on the specified HMAC
key and hash. This procedure does not raise script errors.



Private Procedure "appendLogFile" (from "common.tcl")

    Required argument "fileName"
    Required argument "data"

This Tcl procedure appends binary data to the specified log file. No
trailing new line is emitted. The log file may be created if needed.



Private Procedure "htmlize" (from "common.tcl")

    Required argument "value"

This Tcl procedure (which uses a Fossil TH1 command) returns the HTML
escaped version of the specified string value. If TH1 integration is
not available for any reason, a script error will be raised.



Private Procedure "httpize" (from "common.tcl")

    Required argument "value"

This Tcl procedure (which uses a Fossil TH1 command) returns the HTTP
escaped version of the specified string value. If TH1 integration is
not available for any reason, a script error will be raised.



Private Procedure "getTablePreHeader" (from "common.tcl")

    Required argument "title"

This Tcl procedure (which uses a Fossil TH1 command) returns the HTML
necessary for some header text to accompany a table containing data.
The title will be HTML escaped. If TH1 integration is not available
for any reason, a script error will be raised.



Private Procedure "emitLink" (from "common.tcl")

    Required argument "href"
    Required argument "value"

This Tcl procedure returns the HTML necessary for a link to another
(arbitrary) page. The href argument must be a properly formed URI
and must not contain any characters reserved in HTML; however, the
value will be properly escaped. The value will be used as the text
for the link.



Private Procedure "emitBoldLink" (from "common.tcl")

    Required argument "href"
    Required argument "value"

This Tcl procedure returns the HTML necessary for a link to another
(arbitrary) page. The href argument must be a properly formed URI
and must not contain any characters reserved in HTML; however, the
value will be properly escaped. The value will be used as the text
for the link -AND- it will have bold styling.



Private Procedure "emitCodeLink" (from "common.tcl")

    Required argument "code"
    Required argument "value"

This Tcl procedure returns the HTML necessary for a link to another
page within the Fossil repository. The code argument must be a URN
name and must not contain any characters reserved in HTML; however,
the value will be properly escaped. The value will be used as the
text for the link.



Private Procedure "emitFormLink" (from "common.tcl")

    Required argument "name"
    Required argument "value"
    Required argument "extra"

This Tcl procedure returns the HTML necessary for a link to another
documentation page within the Fossil repository. It is hard-coded
to the latest trunk check-in. The name argument must be the name
of an existing wiki, markdown, or TH1 page and must not contain any
characters reserved in HTML; however, the value will be properly
escaped. The extra argument is designed to facilitate inclusion of
arbitrary query parameters. It should be an empty string if query
parameters are not required. The value will be used as the text for
the link.



Private Procedure "emitFormBoldLink" (from "common.tcl")

    Required argument "name"
    Required argument "value"
    Required argument "extra"

This Tcl procedure returns the HTML necessary for a link to another
documentation page within the Fossil repository. It is hard-coded
to the latest trunk check-in. The name argument must be the name
of an existing wiki, markdown, or TH1 page and must not contain any
characters reserved in HTML; however, the value will be properly
escaped. The extra argument is designed to facilitate inclusion of
arbitrary query parameters. It should be an empty string if query
parameters are not required. The value will be used as the text for
the link -AND- it will have bold styling.



Private Procedure "setupLogGlobals" (from "log.tcl")

This TH1 procedure initializes the global variables used by this script
file. There are no arguments. It must not raise script errors.



Private Procedure "getLogDb" (from "log.tcl")

    Required argument "varName"

This Tcl procedure returns a fully qualified path and file name for
the database of log messages. There are no arguments.



Private Procedure "openAndSetupLogDb" (from "log.tcl")

    Required argument "cmdName"
    Required argument "readOnly"
    Required argument "functions"

This Tcl procedure attempts to open the database of log messages
and enable the options it needs, e.g. via PRAGMA, etc. The custom
function is registered when the functions argument is non-zero.
The readOnly argument should be non-zero to prevent writes to the
database.



Private Procedure "getIdFromApiKey" (from "log.tcl")

    Required argument "apiKey"

This Tcl procedure attempts to obtain an Id based on an API key.
Another connection to the database of variable names and values
will be opened and closed by this procedure, even if one is already
open. An empty string will be returned if the API key is not found;
otherwise, a non-empty string will be returned, which will be the
integer identifier associated with the API key.



Private Procedure "getIdAndHmacKeyFromApiKey" (from "log.tcl")

    Required argument "apiKey"

This Tcl procedure attempts to obtain an Id and HMAC key based on
an API key. Another connection to the database of variable names
and values will be opened and closed by this procedure, even if
one is already open. An empty list will be returned if the API
key is not found; otherwise, a two element list will be returned,
where the first element is the integer identifier associated with
the API key and the second element is the HMAC key associated with
the API key. This is shared by the "log.tcl" and "var.tcl" files.



Private Procedure "maybeCreateLogWhereClause" (from "log.tcl")

    Required argument "type"
    Required argument "whereClauseVarName"
    Required argument "whereTextVarName"
    Optional argument list "args"

This Tcl procedure attempts to create a WHERE clause for the log
table of the database, based on a list of search terms filtered
using the LIKE operator. If the list of search terms is empty,
there will be an empty WHERE clause. The return value of this
procedure is undefined.



Private Procedure "setupTimeGlobals" (from "time.tcl")

This TH1 procedure initializes the global variables used by this script
file. There are no arguments. It must not raise script errors.



Private Procedure "getTimeInUtc" (from "time.tcl")

    Required argument "raw"

This Tcl procedure returns the current time (as UTC) as a formatted
value -OR- as a raw number of (wide integer) milliseconds since the
Unix epoch. The raw argument can be non-zero if the caller wishes
to obtain the raw number of (wide integer) milliseconds since the
Unix epoch.



Private Procedure "setupUrnGlobals" (from "urn.tcl")

This TH1 procedure initializes the global variables used by this script
file. There are no arguments. If Tcl integration is not available for
any reason, a script error will be raised.



Private Procedure "getUrnDb" (from "urn.tcl")

    Required argument "varName"

This Tcl procedure returns a fully qualified path and file name for
the database of URNs. There are no arguments.



Private Procedure "openAndSetupUrnDb" (from "urn.tcl")

    Required argument "cmdName"
    Required argument "readOnly"
    Required argument "functions"

This Tcl procedure attempts to open the database of URNs and enable
the options it needs, e.g. via PRAGMA, etc. The readOnly argument
should be non-zero to prevent writes to the database.



Private Procedure "hasFallbackCodePrefix" (from "urn.tcl")

    Required argument "code"
    Optional argument "prefixVarName" with default value ""
    Optional argument "codeVarName" with default value ""

This Tcl procedure checks if the specified URN code has a prefix
that looks like a fallback. In that case, extract the server and
link identifiers from the code argument and modify the specified
variable names, from the prefixVarName and codeVarName arguments,
in the context of the caller to contain the server identifier and
link identifier, respectively. A non-zero value will be returned
if the fallback detection was successful. This procedure should
not raise script errors.



Private Procedure "getFallbackUri" (from "urn.tcl")

    Required argument "prefix"
    Required argument "code"

This Tcl procedure formats a URI, using the fallback prefix and code
values obtained from the [hasFallbackCodePrefix] procedure. This
procedure cannot really fail and should not raise script errors.



Private Procedure "hasVariableCodePrefix" (from "urn.tcl")

    Required argument "code"
    Optional argument "varName" with default value ""

This Tcl procedure checks if the specified URN code has a prefix
that looks like a network variable reference. In that case, extract
the name of the referenced network variable from the code argument
and modify the specified variable name, from the varName argument, in
the context of the caller to contain the name of the referenced
network variable. A non-zero value will be returned if the network
variable name detection was successful. This procedure should not
raise script errors.



Private Procedure "setupVarGlobals" (from "var.tcl")

This TH1 procedure initializes the global variables used by this script
file. There are no arguments. It must not raise script errors.



Private Procedure "getVarDb" (from "var.tcl")

    Required argument "varName"

This Tcl procedure returns a fully qualified path and file name for
the database of variable names and values. There are no arguments.



Private Procedure "openAndSetupVarDb" (from "var.tcl")

    Required argument "cmdName"
    Required argument "readOnly"

This Tcl procedure attempts to open the database of variable names
and values and enable the options it needs, e.g. via PRAGMA, etc.
The readOnly argument should be non-zero to prevent writes to the
database.