utilities-procs-naviserver.tcl

Publicity: Public Only All

utilities-procs-naviserver.tcl

Provides a variety of non-ACS-specific utilities, including the procs to support the who's online feature.

Location:

packages/acs-tcl/tcl/utilities-procs-naviserver.tcl
Created:

13 April 2000
Author:

Various <acs@arsdigita.com>
CVS Identification:

$Id: utilities-procs-naviserver.tcl,v 1.6 2024/09/11 06:15:48 gustafn Exp $

Procedures in this file

Detailed information

ad_get_cookie (public)

 ad_get_cookie [ -include_set_cookies include_set_cookies ] name \
    [ default ]

Returns the value of a cookie, or $default if none exists.

Switches:

-include_set_cookies (optional, defaults to "t")

Parameters:

name (required)

default (optional)

See Also:

ad_set_cookie
ad_unset_cookie
ad_get_signed_cookie

Partial Call Graph (max 5 caller/called nodes):

Testcases:
test_set_cookie_procs, cookie_consent__setup

ad_mutex_eval (public)

 ad_mutex_eval mutex script

Compatibility proc for handling differences between NaviServer and AOLserver since AOLserver does not support "ns_mutex eval".

Parameters:

mutex (required)

script (required)

Author:

Gustaf Neumann

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

ad_set_cookie (public)

 ad_set_cookie [ -replace replace ] [ -secure secure ] \
    [ -expire expire ] [ -max_age max_age ] [ -domain domain ] \
    [ -path path ] [ -discard discard ] [ -scriptable scriptable ] \
    [ -samesite samesite ] name [ value ]

Sets a cookie. Cookies are name/value pairs stored in a client's browser and are typically sent back to the server of origin with each request.

Switches:

-replace (optional, defaults to "f")
forces the current output headers to be checked for the same cookie. If the same cookie is set for a second time without the replace option being specified, the client will receive both copies of the cookie.
-secure (optional, defaults to "f")
specifies to the user agent that the cookie should only be transmitted back to the server of secure transport.
-expire (optional, defaults to "f")
specifies whether we should expire (clear) the cookie. Setting Max-Age to zero ought to do this, but it doesn't in some browsers (tested on IE 6).
-max_age (optional)
specifies the maximum age of the cookies in seconds (consistent with RFC 2109). max_age "inf" specifies cookies that never expire. The default behavior is to issue session cookies.
-domain (optional)
specifies the domain(s) to which this cookie applies. See RFC2109 for the semantics of this cookie attribute.
-path (optional, defaults to "/")
specifies a subset of URLs to which this cookie applies. It must be a prefix of the URL being accessed.
-discard (optional, defaults to "f")
instructs the user agent to discard the cookie when the user agent terminates.
-scriptable (optional, defaults to "t")
If the scriptable option is false or not given the cookie is unavailable to JavaScript on the client. This can prevent cross site scripting attacks (XSS) on clients which support the HttpOnly option. Set -scriptable to true if you need to access the cookie via javascript. For compatibility reasons with earlier versions, OpenACS 5.8 has the default set to "true". OpenACS 5.9 will have the flag per default set to "false".
-samesite (optional, defaults to "none")

Parameters:

name (required)

value (optional)
is automatically URL encoded.

See Also:

ad_get_cookie
ad_unset_cookie
ad_set_signed_cookie

Partial Call Graph (max 5 caller/called nodes):

Testcases:
test_set_cookie_procs, cookie_consent__setup

ad_unset_cookie (public)

 ad_unset_cookie [ -secure secure ] [ -domain domain ] [ -path path ] \
    [ -samesite samesite ] name

Un-sets a cookie.

Switches:

-secure (optional, defaults to "f")
-domain (optional)
-path (optional, defaults to "/")
-samesite (optional, defaults to "lax")

Parameters:

name (required)

See Also:

ad_get_cookie
ad_set_cookie

Partial Call Graph (max 5 caller/called nodes):

Testcases:
fs_create_folder

ad_urldecode_path (public)

 ad_urldecode_path string

Decode provided string with url-encoding for paths segments (instead of query segments) as defined in RFC 3986

Parameters:

string (required)

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

ad_urldecode_query (public)

 ad_urldecode_query string

Decode provided string with url-encoding for query segments (instead of path segments) as defined in RFC 3986

Parameters:

string (required)

Partial Call Graph (max 5 caller/called nodes):

Testcases:
acs_api_browser_apidoc_format_see, acs_api_browser_apidoc_tclcode_to_html

ad_urlencode_folder_path (public)

 ad_urlencode_folder_path folder_path

Perform an urlencode operation on the segments of the provided folder path, i.e. for a full folder path rather than path segments as in ad_urlencode_path.

Parameters:

folder_path (required)

See Also:

ad_urlencode_path

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

ad_urlencode_path (public)

 ad_urlencode_path string

Encode provided string with url-encoding for paths segments (instead of query segments) as defined in RFC 3986

Parameters:

string (required)

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

ad_urlencode_query (public)

 ad_urlencode_query string

Encode provided string with url-encoding for query segments (instead of paths) as defined in RFC 3986

Parameters:

string (required)

Partial Call Graph (max 5 caller/called nodes):

Testcases:
create_folder_with_page, create_form_with_form_instance

[ hide source ] | [ make this the default ]

Content File Source

ad_library {

    Provides a variety of non-ACS-specific utilities, including
    the procs to support the who's online feature.

    @author Various (acs@arsdigita.com)
    @creation-date 13 April 2000
    @cvs-id $Id: utilities-procs-naviserver.tcl,v 1.6 2024/09/11 06:15:48 gustafn Exp $
}


if {[ns_info name] ne "NaviServer"} {
    return
}

#-------------------------------------------------------------------------
# NaviServer implementation of ad_url(en|de)code* procs
#-------------------------------------------------------------------------

ad_proc -public ad_urlencode_folder_path { folder_path } {

    Perform an urlencode operation on the segments of the provided
    folder path, i.e. for a full folder path rather than path segments
    as in ad_urlencode_path.

    @see ad_urlencode_path
} {
    if {$folder_path ne ""} {
        return [ns_urlencode -part path -- {*}[split $folder_path /]]
    } else {
        return ""
    }
}

ad_proc -public ad_urlencode_path { string } {
    Encode provided string with url-encoding for paths segments
    (instead of query segments) as defined in RFC 3986
} {
    return [ns_urlencode -part path -- $string]
}

ad_proc -public ad_urldecode_path { string } {
    Decode provided string with url-encoding for paths segments
    (instead of query segments) as defined in RFC 3986
} {
    return [ns_urldecode -part path -- $string]
}

ad_proc -public ad_urlencode_query { string } {
    Encode provided string with url-encoding for query segments
    (instead of paths) as defined in RFC 3986
} {
    return [ns_urlencode -part query -- $string]
}

ad_proc -public ad_urldecode_query { string } {
    Decode provided string with url-encoding for query segments
    (instead of path segments) as defined in RFC 3986
} {
    return [ns_urldecode -part query -- $string]
}

#-------------------------------------------------------------------------
# Cookie operations based on NaviServer primitives
#-------------------------------------------------------------------------

d_proc -public ad_unset_cookie {
    {-secure f}
    {-domain ""}
    {-path "/"}
    {-samesite lax}
    name
} {
    Un-sets a cookie.

    @see ad_get_cookie
    @see ad_set_cookie
} {
    if {[::acs::icanuse "ns_deletecookie -samesite"]} {
        ns_deletecookie -domain $domain -path $path -replace t -secure $secure -samesite $samesite -- $name
    } else {
        ns_deletecookie -domain $domain -path $path -replace t -secure $secure -- $name
    }
}

#
# Get Cookie
#
d_proc -public ad_get_cookie {
    { -include_set_cookies t }
    name
    { default "" }
} {
    Returns the value of a cookie, or $default if none exists.

    @see ad_set_cookie
    @see ad_unset_cookie
    @see ad_get_signed_cookie
} {
    ns_getcookie -include_set_cookies $include_set_cookies -- $name $default
}
#
# Set Cookie
#
d_proc -public ad_set_cookie {
    {-replace f}
    {-secure f}
    {-expire f}
    {-max_age ""}
    {-domain ""}
    {-path "/"}
    {-discard f}
    {-scriptable t}
    {-samesite none}
    name
    {value ""}
} {

    Sets a cookie.  Cookies are name/value pairs stored in a client's
    browser and are typically sent back to the server of origin with
    each request.

    @param max_age specifies the maximum age of the cookies in
    seconds (consistent with RFC 2109). max_age "inf" specifies cookies
    that never expire. The default behavior is to issue session
    cookies.

    @param expire specifies whether we should expire (clear) the cookie.
    Setting Max-Age to zero ought to do this, but it doesn't in some browsers
    (tested on IE 6).

    @param path specifies a subset of URLs to which this cookie
    applies. It must be a prefix of the URL being accessed.

    @param domain specifies the domain(s) to which this cookie
    applies. See RFC2109 for the semantics of this cookie attribute.

    @param secure specifies to the user agent that the cookie should
    only be transmitted back to the server of secure transport.

    @param replace forces the current output headers to be checked for
    the same cookie. If the same cookie is set for a second time
    without the replace option being specified, the client will
    receive both copies of the cookie.

    @param discard instructs the user agent to discard the cookie when
    the user agent terminates.

    @param scriptable If the scriptable option is false or not given
    the cookie is unavailable to JavaScript on the client. This can
    prevent cross site scripting attacks (XSS) on clients which
    support the HttpOnly option. Set -scriptable to true if you need
    to access the cookie via javascript. For compatibility reasons
    with earlier versions, OpenACS 5.8 has the default set to
    "true". OpenACS 5.9 will have the flag per default set to "false".

    @param value is automatically URL encoded.

    @see ad_get_cookie
    @see ad_unset_cookie
    @see ad_set_signed_cookie
} {


    if { $expire == "f"} {
        set expire -1
    } elseif {$max_age ne ""} {
        if {$max_age eq "inf"} {
            set expire -1
        } else {
            set expire [expr {[ns_time] + $max_age}]
        }
    }

    if {$samesite ne "none" && [::acs::icanuse "ns_setcookie -samesite"]} {
        set samesiteFlag "-samesite $samesite"
    } else {
        set samesiteFlag ""
    }
    ns_setcookie -discard $discard -domain $domain -expires $expire -path $path \
        -replace $replace -scriptable $scriptable -secure $secure {*}$samesiteFlag -- \
        $name $value
}

#-------------------------------------------------------------------------
# Provide a clean way of handling exceptions in mutexed regions
# (between locking and unlocking of a mutex). Should be used probably
# on more places in OpenACS.
#-------------------------------------------------------------------------

ad_proc -public ad_mutex_eval {mutex script} {

    Compatibility proc for handling differences between NaviServer
    and AOLserver since AOLserver does not support "ns_mutex
    eval".

    @author Gustaf Neumann

} {
    uplevel [list ns_mutex eval $mutex $script]
}


# Local variables:
#    mode: tcl
#    tcl-indent-level: 4
#    indent-tabs-mode: nil
# End: