1/* Licensed to the Apache Software Foundation (ASF) under one or more
2 * contributor license agreements.  See the NOTICE file distributed with
3 * this work for additional information regarding copyright ownership.
4 * The ASF licenses this file to You under the Apache License, Version 2.0
5 * (the "License"); you may not use this file except in compliance with
6 * the License.  You may obtain a copy of the License at
7 *
8 *     http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17#ifndef MOD_SESSION_H
18#define MOD_SESSION_H
19
20/* Create a set of SESSION_DECLARE(type), SESSION_DECLARE_NONSTD(type) and
21 * SESSION_DECLARE_DATA with appropriate export and import tags for the platform
22 */
23#if !defined(WIN32)
24#define SESSION_DECLARE(type)        type
25#define SESSION_DECLARE_NONSTD(type) type
26#define SESSION_DECLARE_DATA
27#elif defined(SESSION_DECLARE_STATIC)
28#define SESSION_DECLARE(type)        type __stdcall
29#define SESSION_DECLARE_NONSTD(type) type
30#define SESSION_DECLARE_DATA
31#elif defined(SESSION_DECLARE_EXPORT)
32#define SESSION_DECLARE(type)        __declspec(dllexport) type __stdcall
33#define SESSION_DECLARE_NONSTD(type) __declspec(dllexport) type
34#define SESSION_DECLARE_DATA         __declspec(dllexport)
35#else
36#define SESSION_DECLARE(type)        __declspec(dllimport) type __stdcall
37#define SESSION_DECLARE_NONSTD(type) __declspec(dllimport) type
38#define SESSION_DECLARE_DATA         __declspec(dllimport)
39#endif
40
41/**
42 * @file  mod_session.h
43 * @brief Session Module for Apache
44 *
45 * @defgroup MOD_SESSION mod_session
46 * @ingroup  APACHE_MODS
47 * @{
48 */
49
50#include "apr_hooks.h"
51#include "apr_optional.h"
52#include "apr_tables.h"
53#include "apr_uuid.h"
54#include "apr_pools.h"
55#include "apr_time.h"
56
57#include "httpd.h"
58#include "http_config.h"
59#include "ap_config.h"
60
61#define MOD_SESSION_NOTES_KEY "mod_session_key"
62
63/**
64 * Define the name of a username stored in the session, so that modules interested
65 * in the username can find it in a standard place.
66 */
67#define MOD_SESSION_USER "user"
68
69/**
70 * Define the name of a password stored in the session, so that modules interested
71 * in the password can find it in a standard place.
72 */
73#define MOD_SESSION_PW "pw"
74
75/**
76 * A session structure.
77 *
78 * At the core of the session is a set of name value pairs making up the
79 * session.
80 *
81 * The session might be uniquely identified by an anonymous uuid, or
82 * a remote_user value, or both.
83 */
84typedef struct {
85    apr_pool_t *pool;             /* pool to be used for this session */
86    apr_uuid_t *uuid;             /* anonymous uuid of this particular session */
87    const char *remote_user;      /* user who owns this particular session */
88    apr_table_t *entries;         /* key value pairs */
89    const char *encoded;          /* the encoded version of the key value pairs */
90    apr_time_t expiry;            /* if > 0, the time of expiry of this session */
91    long maxage;                  /* if > 0, the maxage of the session, from
92                                   * which expiry is calculated */
93    int dirty;                    /* dirty flag */
94    int cached;                   /* true if this session was loaded from a
95                                   * cache of some kind */
96    int written;                  /* true if this session has already been
97                                   * written */
98} session_rec;
99
100/**
101 * Structure to carry the per-dir session config.
102 */
103typedef struct {
104    int enabled;                  /* whether the session has been enabled for
105                                   * this directory */
106    int enabled_set;
107    long maxage;                  /* seconds until session expiry */
108    int maxage_set;
109    const char *header;           /* header to inject session */
110    int header_set;
111    int env;                      /* whether the session has been enabled for
112                                   * this directory */
113    int env_set;
114    apr_array_header_t *includes; /* URL prefixes to be included. All
115                                   * URLs included if empty */
116    apr_array_header_t *excludes; /* URL prefixes to be excluded. No
117                                   * URLs excluded if empty */
118} session_dir_conf;
119
120/**
121 * Hook to load the session.
122 *
123 * If the session doesn't exist, a blank one will be created.
124 *
125 * @param r The request
126 * @param z A pointer to where the session will be written.
127 */
128APR_DECLARE_EXTERNAL_HOOK(ap, SESSION, apr_status_t, session_load,
129        (request_rec * r, session_rec ** z))
130
131/**
132 * Hook to save the session.
133 *
134 * In most implementations the session is only saved if the dirty flag is
135 * true. This prevents the session being saved unnecessarily.
136 *
137 * @param r The request
138 * @param z A pointer to where the session will be written.
139 */
140APR_DECLARE_EXTERNAL_HOOK(ap, SESSION, apr_status_t, session_save,
141        (request_rec * r, session_rec * z))
142
143/**
144 * Hook to encode the session.
145 *
146 * In the default implementation, the key value pairs are encoded using
147 * key value pairs separated by equals, in turn separated by ampersand,
148 * like a web form.
149 *
150 * @param r The request
151 * @param z A pointer to where the session will be written.
152 */
153APR_DECLARE_EXTERNAL_HOOK(ap, SESSION, apr_status_t, session_encode,
154        (request_rec * r, session_rec * z))
155
156/**
157 * Hook to decode the session.
158 *
159 * In the default implementation, the key value pairs are encoded using
160 * key value pairs separated by equals, in turn separated by ampersand,
161 * like a web form.
162 *
163 * @param r The request
164 * @param z A pointer to where the session will be written.
165 */
166APR_DECLARE_EXTERNAL_HOOK(ap, SESSION, apr_status_t, session_decode,
167        (request_rec * r, session_rec * z))
168
169APR_DECLARE_OPTIONAL_FN(
170        apr_status_t,
171        ap_session_get,
172        (request_rec * r, session_rec * z, const char *key, const char **value));
173APR_DECLARE_OPTIONAL_FN(apr_status_t, ap_session_set,
174        (request_rec * r, session_rec * z, const char *key, const char *value));
175APR_DECLARE_OPTIONAL_FN(apr_status_t, ap_session_load,
176        (request_rec *, session_rec **));
177APR_DECLARE_OPTIONAL_FN(apr_status_t, ap_session_save,
178        (request_rec *, session_rec *));
179
180/**
181 * The name of the module.
182 */
183extern module AP_MODULE_DECLARE_DATA session_module;
184
185#endif /* MOD_SESSION_H */
186/** @} */
187