Functions beginning with V
The following functions are discussed in this section:
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 | Return Values |
|---|---|
int vs_alloc_slot(void);
|
A slot number if the function succeeds, or -1 if fails. |
See Also
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 | Return Values | Parameters |
|---|---|---|
void* vs_get_data(const VirtualServer* vs, int slot); |
The value of the pointer previously stored using vs_set_data or NULL on failure. | 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_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 | Return Values | Parameters |
|---|---|---|
httpd_object* vs_get_default_httpd_object(VirtualServer* vs); |
A pointer the default httpd_object, or NULL on failure. Do not FREE this object. | 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 | Return Values | Parameters |
|---|---|---|
char* vs_get_doc_root(const VirtualServer* vs); |
A pointer to a string representing the full operating system path to the document root. The caller must FREE this string. | 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 | Return Values | Parameters |
|---|---|---|
httpd_objset* vs_get_httpd_objset(VirtualServer* vs); |
A pointer to the httpd_objset, or NULL on failure. Do not FREE this objset. | VirtualServer* vs represents the virtual server for which the function ID to find the objset. |
See Also
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 | Return Values | Parameters |
|---|---|---|
const char* vs_get_id(const VirtualServer* vs); |
A pointer to a string representing the virtual server ID. Do not FREE this string. | const VirtualServer* vs represents the virtual server of interest. |
See Also
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 | Return Values | Parameters |
|---|---|---|
char* vs_get_mime_type(const VirtualServer* vs, const char* uri); |
A pointer to a string representing the MIME type. The caller must FREE this string. | 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 | Return Values | Parameters |
|---|---|---|
const char* vs_lookup_config_var(const VirtualServer* vs, const char* name); |
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. | 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 | Return Values | Parameters |
|---|---|---|
int vs_register_cb(VSInitFunc* initfn, VSDestroyFunc* destroyfn);
|
The constant REQ_PROCEED if the operation succeeds. The constant REQ_ABORTED if the operation fails. |
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 | Return Values | Parameters |
|---|---|---|
void* vs_set_data(const VirtualServer* vs, int* slot, void* data); |
Data on success, or NULL on failure. | 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_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 | Return Values | Parameters |
|---|---|---|
char* vs_translate_uri(const VirtualServer* vs, const char* uri); |
A pointer to a string representing the full operating system path for the given URI. The caller must FREE this string. | 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. |
Sign up or Log in to add a comment or watch this page.