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*.

Syntax

int vs_alloc_slot(void);

Return Values

A slot number if the function succeeds, or -1 if fails.

See Also

vs_get_data() Function, vs_set_data() Function

vs_get_data() Function

The vs_get_data function finds the value of a pointer to data for a given VirtualServer* and slot. The slot must be a slot number returned from vs_alloc_slot or vs_set_data.

Syntax

void* vs_get_data(const VirtualServer* vs, int slot);

Return Values

The value of the pointer previously stored using vs_set_data or NULL on failure.

Parameters

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

int slot is the slot number to retrieve the pointer from.

See Also

vs_set_data() Function, vs_alloc_slot() Function

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_httpd_objset() Function, vs_register_cb() Function

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_default_httpd_object() Function, vs_register_cb() Function

vs_get_id() Function

The vs_get_id function finds the ID of a VirtualServer*.

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.

Parameters

const VirtualServer* vs represents the virtual server of interest.

See Also

vs_register_cb() Function, request_get_vs() Function

vs_get_mime_type() Function

The vs_get_mime_type function determines the MIME type that would be returned in the content-type: header for the given URI.

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

Syntax

char* vs_get_mime_type(const VirtualServer* vs, const char* uri);

Return Values

A pointer to a string representing the MIME type. The caller must FREE this string.

Parameters

const VirtualServer* vs represents the virtual server of interest.

const char* uri is the URI whose MIME type is of interest.

vs_lookup_config_var() Function

The vs_lookup_config_var function finds the value of a configuration variable for a given virtual server.

Do not FREE the returned string.

Syntax

const char* vs_lookup_config_var(const VirtualServer* vs, const char* name);

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.

int* slot is the slot number at which to store the pointer.

void* data is the pointer to store.

See Also

vs_get_data() Function, vs_alloc_slot() Function, vs_register_cb() Function

vs_translate_uri() Function

The vs_translate_uri function translates a URI as though the URI were part of a request for a specific virtual server. The returned string is the full operating system path.

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

Syntax

char* vs_translate_uri(const VirtualServer* vs, const char* uri);

Return Values

A pointer to a string representing the full operating system path for the given URI. The caller must FREE this string.

Parameters

const VirtualServer* vs represents the virtual server for which to translate the URI.

const char* uri is the URI to translate to an operating system path.