V

vs_alloc_slot() Function

The vs_alloc_slot function allocates a new slot for
storing a pointer to data specific to a certain VirtualServer*.
The returned slot number can be used in subsequent vs_set_data and vs_get_data calls. The returned slot number is valid for any VirtualServer*.

The value of the pointer, which may be returned by a call to vs_set_data , defaults to NULL for every VirtualServer*.

Parameters

See Also

vs_get_default_httpd_object() Function

The vs_get_default_httpd_object function obtains
a pointer to the default (or root) httpd_object from the
virtual server's httpd_objset in the configuration defined
by the obj.conf file of the virtual server class. The default
object is typically named default. Plug-ins may only modify
the httpd_object at VSInitFunc time.
See vs_register_cb() Function for an explanation
of VSInitFunc time.

Do not FREE the returned object.

Syntax

httpd_object* vs_get_default_httpd_object(VirtualServer* vs);

Return Values

A pointer the default httpd_object, or NULL on failure.
Do not FREE this object.

Parameters

VirtualServer* vs represents the virtual server for
which to find the default object.

See Also

vs_get_doc_root() Function

The vs_get_doc_root function finds the document root
for a virtual server. The returned string is the full operating system path
to the document root.

The caller should FREE the returned string when done with it.

Syntax

char* vs_get_doc_root(const VirtualServer* vs);

Return Values

A pointer to a string representing the full operating system path to
the document root. The caller must FREE this string.

Parameters

const VirtualServer* vs represents the virtual server
for which to find the document root.

vs_get_httpd_objset() Function

The vs_get_httpd_objset function obtains a pointer
to the httpd_objset, the configuration defined by the obj.conf file of the virtual server class for a given virtual server.
Plug-ins may only modify the httpd_objset at VSInitFunc time. See vs_register_cb() Function for
an explanation of VSInitFunc time.

Do not FREE the returned objset.

Syntax

httpd_objset* vs_get_httpd_objset(VirtualServer* vs);

Return Values

A pointer to the httpd_objset, or NULL on failure.
Do not FREE this objset.

Parameters

VirtualServer* vs represents the virtual server for
which the function ID to find the objset.

See Also

vs_get_id() Function

The ID of a virtual server is a unique null-terminated string that remains
constant across configurations. While IDs remain constant across configurations,
the value of VirtualServer* pointers do not.

Do not FREE the virtual server ID string. If called during request processing,
the string will remain valid for the duration of the current request. If called
during VSInitFunc processing, the string will remain valid
until after the corresponding VSDestroyFunc function has
returned. For more information, see vs_register_cb() Function.

To retrieve a VirtualServer* that is valid only for
the current request, use request_get_vs.

Syntax

const char* vs_get_id(const VirtualServer* vs);

Return Values

A pointer to a string representing the virtual server ID. Do not FREE
this string.

Syntax

Return Values

A pointer to a string representing the value of variable name on success,
or NULL if variable name was not found. Do not FREE this string.

Parameters

const VirtualServer* vs represents the virtual server
of interest.

const char* name is the name of the configuration
variable.

vs_register_cb() Function

The vs_register_cb function enables a plug-in to
register functions that will receive notifications of virtual server initialization
and destruction events. The vs_register_cb function is
typically called from an Init SAF in magnus.conf.

When a new configuration is loaded, all registered VSInitFunc (virtual
server initialization) callbacks are called for each of the virtual servers
before any requests are served from the new configuration. VSInitFunc callbacks
are called in the same order they were registered. The first callback registered
is the first callback called.

When the last request has been served from an old configuration, all
registered VSDestroyFunc (virtual server destruction) callbacks
are called for each of the virtual servers before any virtual servers are
destroyed. VSDestroyFunc callbacks are called in reverse
order. The first callback registered is the last callback called.

Either initfn or destroyfn may
be NULL if the caller is not interested in callbacks for initialization or
destruction, respectively.

Syntax

int vs_register_cb(VSInitFunc* initfn, VSDestroyFunc* destroyfn);

Return Values

The constant REQ_PROCEED if the operation succeeds.

The constant REQ_ABORTED if the operation fails.

Parameters

VSInitFunc* initfn is a pointer to the function to
call at virtual server initialization time, or NULL if the caller is not interested
in virtual server initialization events.

VSDestroyFunc* destroyfn is a pointer to the function
to call at virtual server destruction time, or NULL if the caller is not interested
in virtual server destruction events.

vs_set_data() Function

The vs_set_data function sets the value of a pointer
to data for a given virtual server and slot. The *slot must
be -1 or a slot number returned from vs_alloc_slot.
If *slot is -1, vs_set_data calls vs_alloc_slot implicitly and returns the new slot number in *slot.

The stored pointer is maintained on a per-VirtualServer* basis,
not a per-ID basis. Distinct VirtualServer*s from different
configurations might exist simultaneously with the same virtual server IDs.
However, because these configurations are distinct VirtualServer*s,
each configuration has its own VirtualServer*-specific
data. As a result, vs_set_data should generally not be
called outside of VSInitFunc processing. See vs_register_cb() Function for an explanation of VSInitFunc processing.

Syntax

void* vs_set_data(const VirtualServer* vs, int* slot, void* data);

Return Values

Data on success, or NULL on failure.

Parameters

const VirtualServer* vs represents the virtual server
to set the pointer for.