HttpServer.h File Reference

#include "TargConfig.h"
#include "HttpConnection.h"
#include "DoubleList.h"
#include "SingleList.h"
#include "SoDisp.h"
#include "SplayTree.h"
#include "BaErrorCodes.h"
#include "BufPrint.h"
#include "IoIntf.h"
#include <string.h>
#include <stddef.h>

Include dependency graph for HttpServer.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	HttpInData
	The web-server "Request Data" container. More...
struct	HttpParameter
	A persistent container object for HTTP parameters. More...
struct	HttpParameterIterator
	The HttpParameterIterator is used for iterating through the form elements parsed by the HttpServer object. More...
struct	HttpCookie
	A cookie is used for exchanging a small amount of information between a HttpPage and a web browser. More...
struct	HttpStdHeaders
	Standard HTTP header values. More...
struct	HttpRequest
	The HttpServer creates an HttpRequest object when the HttpServer parses a client request. More...
struct	HttpResponse
	This object is used when sending response messages back to the client. More...
struct	HttpCommand
	The HttpCommand class is a container class for the HttpRequest and HttpResponse command pair. More...
struct	HttpSessionAttribute
	The interface to an HttpSession attribute. More...
struct	HttpSession
	Provides a way to identify a user across more than one page request or visit to a web site, and to store information about that user. More...
struct	HttpSessionContainer
	The HttpSession container class. More...
struct	HttpPage
	An HttpPage, which is typically created by the CSP compiler, is similar to a Java servlet. More...
struct	HttpDir
	An instance of the HttpDir class, which is a collection of zero or more resources, serves as one directory entry in the virtual file system. More...
struct	HttpServerConfig
	Use an instance of this class if you want to override the default web-server parameters. More...
struct	HttpServer
	The Web Server. More...

Macros
#define	httpUnescape(s)   httpUnescapeInternal(s,FALSE)
	Decode URL escapes in place. More...
#define	httpFormUnescape(s)   httpUnescapeInternal(s,TRUE)
	Decode form escapes in place, also replacing plus with space. More...

Typedefs
typedef void(*	CspInit) (struct HttpDir *cspRoot, struct CspReader *reader)
	Function prototype for the "initialize function" generated by CspLink. More...
typedef struct HttpInData	HttpInData
	The web-server "Request Data" container. More...
typedef struct HttpParameter	HttpParameter
	A persistent container object for HTTP parameters. More...
typedef struct HttpParameterIterator	HttpParameterIterator
	The HttpParameterIterator is used for iterating through the form elements parsed by the HttpServer object. More...
typedef struct HttpCookie	HttpCookie
	A cookie is used for exchanging a small amount of information between a HttpPage and a web browser. More...
typedef struct HttpStdHeaders	HttpStdHeaders
	Standard HTTP header values. More...
typedef struct HttpRequest	HttpRequest
	The HttpServer creates an HttpRequest object when the HttpServer parses a client request. More...
typedef struct HttpResponse	HttpResponse
	This object is used when sending response messages back to the client. More...
typedef struct HttpCommand	HttpCommand
	The HttpCommand class is a container class for the HttpRequest and HttpResponse command pair. More...
typedef void(*	HttpSessionAttribute_Destructor) (struct HttpSessionAttribute *o)
	HttpSessionAttribute termination callback function. More...
typedef struct HttpSessionAttribute	HttpSessionAttribute
	The interface to an HttpSession attribute. More...
typedef struct HttpSession	HttpSession
	Provides a way to identify a user across more than one page request or visit to a web site, and to store information about that user. More...
typedef struct HttpSessionContainer	HttpSessionContainer
	The HttpSession container class. More...
typedef void(*	HttpPage_Service) (struct HttpPage *page, HttpRequest *request, HttpResponse *response)
	The HttpPage service function. More...
typedef struct HttpPage	HttpPage
	An HttpPage, which is typically created by the CSP compiler, is similar to a Java servlet. More...
typedef int(*	HttpDir_Service) (struct HttpDir *o, const char *relPath, HttpCommand *cmd)
	The HttpDir service callback function. More...
typedef struct HttpDir	HttpDir
	An instance of the HttpDir class, which is a collection of zero or more resources, serves as one directory entry in the virtual file system. More...
typedef struct HttpServerConfig	HttpServerConfig
	Use an instance of this class if you want to override the default web-server parameters. More...
typedef struct HttpServer	HttpServer
	The Web Server. More...

Enumerations
enum	HttpMethod
	HTTP method types. More...

Functions
BA_API void	httpFmtDate (char *buf, U16 bufLen, BaTime t)
	Format an HTTP date in GMT. More...
BA_API char *	httpUnescapeInternal (char *from, BaBool isForm)
	Decode percent followed by two hex digits in place. More...
BA_API char *	httpEscape (char *out, const char *in)
	Encodes characters that cannot be in a http URL. More...
BA_API U32	HttpParameter_calculateSize (struct HttpRequest *req)
	Calculate the HttpParameter size. More...
BA_API HttpParameter *	HttpParameter_clone (void *buf, struct HttpRequest *req)
	Copy HTTP parameters to buf and return as a HttpParameter object. More...
BA_API const char *	HttpParameter_getParameter (HttpParameter *o, const char *paramName)
	Returns the value of a request parameter as a const char*, or null if the parameter does not exist. More...
BA_API int	HttpParameterIterator_constructor (HttpParameterIterator *o, struct HttpRequest *req)
	Initialize an iterator and select its first element. More...
BA_API int	HttpParameterIterator_constructor2 (HttpParameterIterator *o, HttpParameter *param)
	Initialize an iterator and select its first element. More...
BA_API const char *	HttpCookie_getComment (HttpCookie *o)
	Returns the comment set for this cookie or null if the cookie comment is not set. More...
BA_API const char *	HttpCookie_getDomain (HttpCookie *o)
	Returns the domain name set for this cookie. More...
BA_API BaTime	HttpCookie_getMaxAge (HttpCookie *o)
	Returns the maximum age of the cookie, specified in seconds; by default, 0 indicating the cookie will persist until browser shutdown. More...
BA_API const char *	HttpCookie_getName (HttpCookie *o)
	Returns the name of the cookie. More...
BA_API const char *	HttpCookie_getPath (HttpCookie *o)
	Returns the path on the server to which the browser returns this cookie. More...
BA_API BaBool	HttpCookie_getSecure (HttpCookie *o)
	Returns true if the browser is sending cookies only over a secure protocol, or false if the browser can send cookies using any protocol. More...
BA_API BaBool	HttpCookie_getHttpOnly (HttpCookie *o)
	Return the HttpOnly attribute. More...
BA_API const char *	HttpCookie_getValue (HttpCookie *o)
	Returns the value of the cookie. More...
BA_API int	HttpCookie_setComment (HttpCookie *o, const char *purpose)
	Specifies a comment that describes a cookie's purpose. More...
BA_API int	HttpCookie_setDomain (HttpCookie *o, const char *pattern)
	Specifies the domain within which this cookie should be presented. More...
BA_API void	HttpCookie_setMaxAge (HttpCookie *o, BaTime expiry)
	Sets the maximum age of the cookie in seconds. More...
BA_API int	HttpCookie_setPath (HttpCookie *o, const char *uri)
	Set the cookie path. More...
BA_API void	HttpCookie_setSecure (HttpCookie *o, BaBool flag)
	Inform the browser whether the cookie should be sent only using a secure protocol such as HTTPS – i.e. More...
BA_API void	HttpCookie_setHttpOnly (HttpCookie *o, BaBool flag)
	Marks or unmarks this Cookie as HttpOnly. More...
BA_API int	HttpCookie_setValue (HttpCookie *o, const char *newValue)
	Assigns a new value to a cookie after the cookie is created. More...
BA_API void	HttpCookie_activate (HttpCookie *o)
	Activates the cookie. More...
BA_API int	HttpRequest_checkMethods (HttpRequest *o, struct HttpResponse *resp, U32 methods, BaBool addDefault)
	Checks the HTTP method type and sends a response message if condition met. More...
BA_API BaBool	HttpRequest_checkTime (HttpRequest *o, struct HttpResponse *resp, BaTime time)
	Parses and checks if the "If-Modified-Since" time is equal or greater than "time". More...
BA_API const char *	HttpRequest_getRequestURI (HttpRequest *o)
	Returns the pathname. More...
BA_API const char *	HttpRequest_getRequestURL (HttpRequest *o, BaBool forceHttps)
	Reconstructs the URL the client used to make the request. More...
BA_API const char *	HttpRequest_getVersion (HttpRequest *o)
	Returns the HTTP version as a string, normally "1.1". More...
BA_API const char *	HttpRequest_getHeaderValue (HttpRequest *o, const char *name)
	Returns the value of the specified request header. More...
BA_API HttpCookie *	HttpRequest_getCookie (HttpRequest *o, const char *name)
	Returns the requested cookie or NULL if no cookie matches the name. More...
BA_API const char *	HttpRequest_getParameter (HttpRequest *o, const char *paramName)
	Returns the value of a request parameter as a const char* or null if the parameter does not exist. More...
BA_API HttpHeader *	HttpRequest_getHeaders (HttpRequest *o, int *len)
	Return an HTTP header iterator that can iterate and fetch all the HTTP headers. More...
BA_API int	HttpRequest_wsUpgrade (HttpRequest *o)
	Validate and send an HTTP/1.1 WebSocket version-13 handshake. More...
BA_API struct HttpSession *	HttpRequest_getSession (HttpRequest *o, BaBool create)
	Returns the current HttpSession associated with this request, or if there is no current session and create is true, returns a new session. More...
BA_API HttpCookie *	HttpResponse_createCookie (struct HttpResponse *o, const char *name)
	Create a cookie. More...
BA_API const char *	HttpResponse_containsHeader (HttpResponse *o, const char *name)
	Searches the internal response header database for a header with the specified name. More...
BA_API const char *	HttpResponse_encodeRedirectURL (HttpResponse *o, const char *pathName)
	Encodes the specified URL into an absolute URL, or if encoding is not needed, returns the URL unchanged. More...
BA_API const char *	HttpResponse_encodeUrl (HttpResponse *o, const char *path)
	Encodes an absolute or relative URL, or if encoding is not needed, returns the URL unchanged. More...
BA_API int	HttpResponse_flush (HttpResponse *o)
	Forces any content in the buffer to be written to the client. More...
BA_API int	HttpResponse_redirect (HttpResponse *o, const char *path)
	Internally redirects the request to another resource. More...
BA_API int	HttpResponse_setResponseBuf (HttpResponse *o, BufPrint *buf, BaBool useDefBuffer)
	This is an advanced function that makes it possible to redirect the output, which is normally sent to the client, to another buffer. More...
BA_API int	HttpResponse_removeResponseBuf (HttpResponse *o)
	Remove buffer set by using setResponseBuf. More...
BA_API int	HttpResponse_resetHeaders (HttpResponse *o)
	Removes all HTTP headers. More...
BA_API int	HttpResponse_resetBuffer (HttpResponse *o)
	Clears the content of the underlying buffer in the response without clearing headers or status code. More...
BA_API int	HttpResponse_sendBufAsError (HttpResponse *o, int eCode)
	Sends the data formatted into the HttpResponse buffer as an error message to the client. More...
BA_API int	HttpResponse_sendBufAsTxtError (HttpResponse *o, int eCode)
	Sends the data formatted into the HttpResponse buffer as an error message to the client. More...
BA_API int	HttpResponse_sendRedirect (HttpResponse *o, const char *url)
	Sends a temporary redirect (302) response to the client using the specified redirect location URL. More...
BA_API int	HttpResponse_redirect2TLS (HttpResponse *o)
	Prepares an HTTPS redirect (301) for a non-secure connection. More...
BA_API int	HttpResponse_setContentLength (HttpResponse *o, BaFileSize len)
	Sets the "Content-Length" parameter value. More...
BA_API int	HttpResponse_setContentType (HttpResponse *o, const char *type)
	Sets the "Content-Type" parameter value. More...
BA_API int	HttpResponse_setDateHeader (HttpResponse *o, const char *name, BaTime t)
	Set a copied date header; call before response commitment. More...
BA_API int	HttpResponse_setHeader (HttpResponse *o, const char *name, const char *value, BaBool replace)
	Sets a HTTP response header with the given name and value. More...
BA_API int	HttpResponse_setMaxAge (HttpResponse *response, BaTime seconds)
	Sets header "Cache-Control: max-age=seconds". More...
BA_API char *	HttpResponse_fmtHeader (HttpResponse *o, const char *name, int valueLen, BaBool replace)
	Pre-allocate memory for a {name, value} pair in the response header database. More...
BA_API int	HttpResponse_printf (HttpResponse *o, const char *fmt,...)
	printf is used for sending formatted data to the client. More...
BA_API int	HttpResponse_write (HttpResponse *o, const void *data, int len, int useBuffering)
	Used for sending pre-formatted data to the client. More...
BA_API BufPrint *	HttpResponse_getWriter (HttpResponse *o)
	Returns a BufPrint object that can send any type of data to the client. More...
BA_API int	HttpResponse_send (HttpResponse *o, const void *data, int len)
	Used when sending raw data to the client. More...
BA_API int	HttpResponse_setDefaultHeaders (HttpResponse *o)
	Sets the most common header values in servlet and CSP files. More...
BA_API void	HttpSessionAttribute_constructor (HttpSessionAttribute *o, const char *name, HttpSessionAttribute_Destructor d)
	Initialize a session attribute. More...
BA_API void	HttpSessionAttribute_destructor (HttpSessionAttribute *o)
	Terminate an unattached attribute and release its copied name. More...
BA_API HttpSessionAttribute *	HttpSession_getAttribute (HttpSession *o, const char *name)
	Returns the object bound with the specified name in this session, or null if no object is bound under the name. More...
BA_API BaTime	HttpSession_getCreationTime (HttpSession *o)
	Returns the time when this session was created, measured in seconds since midnight January 1, 1970 GMT. More...
BA_API BaTime	HttpSession_getLastAccessedTime (HttpSession *o)
	Returns the last time the client sent a request associated with this session, as the number of seconds since midnight January 1, 1970 GMT, and marked by the time the container received the request. More...
BA_API BaTime	HttpSession_getMaxInactiveInterval (HttpSession *o)
	Returns the maximum time interval, in seconds, that the session container will keep this session open between client accesses. More...
BA_API struct HttpServer *	HttpSession_getServer (HttpSession *o)
	Get the server object. More...
BA_API void	HttpSession_terminate (HttpSession *o)
	Unbinds any objects bound to this session object, runs the HttpSession destructor, and frees the memory for this object. More...
BA_API int	HttpSession_removeAttribute (HttpSession *o, const char *name)
	Removes the object bound with the specified name from this session. More...
BA_API int	HttpSession_setAttribute (HttpSession *o, HttpSessionAttribute *value)
	Binds an object to this session, using the name specified. More...
BA_API void	HttpSession_setMaxInactiveInterval (HttpSession *o, BaTime interval)
	Specifies the time, in seconds, between client requests before the session container will invalidate this session. More...
BA_API void	HttpSession_decrRefCntr (HttpSession *o)
	Decrements the session reference counter. More...
BA_API int	HttpSession_fmtSessionId (HttpSession *o, U8 *buf, size_t bufSize)
	Format the full session token as hexadecimal text. More...
void BA_API	HttpPage_constructor (HttpPage *o, HttpPage_Service service, const char *name)
	The HttpPage constructor. More...
BA_API void	HttpPage_destructor (HttpPage *o)
	The HttpPage destructor unlinks the page from the parent directory. More...
BA_API int	HttpPage_unlink (HttpPage *o)
	Unlinks/removes the page from the parent directory. More...
BA_API void	HttpDir_constructor (HttpDir *o, const char *name, S8 priority)
	Constructor for creating a sub-directory. More...
BA_API void	HttpDir_destructor (HttpDir *o)
	Unlink this directory and notify all child pages/directories through their service callbacks with NULL request arguments. More...
BA_API char *	HttpDir_makeAbsPath (HttpDir *o, const char *relPath, int relPathLen)
	Makes an absolute path based on where the HttpDir instance is installed in the virtual file system and the provided relative path. More...
BA_API int	HttpDir_insertDir (HttpDir *o, HttpDir *dir)
	Insert a sub-directory. More...
BA_API HttpDir *	HttpDir_getDir (HttpDir *o, const char *name)
	Returns the first directory with the name given or NULL if not found. More...
BA_API HttpPage *	HttpDir_getPage (HttpDir *o, const char *name)
	Returns the page with the name given or NULL if not found. More...
BA_API int	HttpDir_insertPage (HttpDir *o, HttpPage *page)
	Insert a page in the directory. More...
BA_API HttpPage *	HttpDir_findPage (HttpDir *o, HttpPage *iter, const char *name)
	Searches for a page in this directory node. More...
BA_API HttpDir *	HttpDir_findDir (HttpDir *iter, const char *name, unsigned int nameLen)
	Searches for a sub-directory in this directory node. More...
BA_API HttpDir *	HttpDir_createOrGet (HttpDir *o, const char *name)
	Returns a sub-directory with the given name. More...
BA_API void	HttpDir_p403 (HttpDir *o, const char *p403)
	Set a 403 denied request handler. More...
BA_API HttpDir_Service	HttpDir_setService (HttpDir *o, HttpDir_Service s)
	Replace the original service function in HttpDir with your own. More...
BA_API int	HttpDir_unlink (HttpDir *o)
	Unlinks/removes the directory from the parent directory. More...
BA_API int	HttpDir_authenticateAndAuthorize (HttpDir *o, HttpCommand *cmd, const char *path)
	Authenticate and authorize the user. More...
BA_API void	HttpServerConfig_constructor (HttpServerConfig *o)
	The constructor sets up the default parameters. More...
BA_API int	HttpServerConfig_setRequest (HttpServerConfig *o, S16 min, S16 max)
	Set the size of the HTTP request buffer. More...
BA_API int	HttpServerConfig_setResponseHeader (HttpServerConfig *o, U16 min, U16 max)
	Set the size of the HTTP response header buffer. More...
BA_API int	HttpServerConfig_setResponseData (HttpServerConfig *o, U16 size)
	The HttpResponse object stores formatted data in the response data buffer. More...
BA_API int	HttpServerConfig_setCommit (HttpServerConfig *o, U16 size)
	Set the size of the HTTP response commit buffer. More...
BA_API int	HttpServerConfig_setNoOfHttpCommands (HttpServerConfig *o, U16 size)
	The number of HttpCommand instances created by the web-server. More...
BA_API int	HttpServerConfig_setNoOfHttpConnections (HttpServerConfig *o, U16 size)
	Number of HttpConnection instances. More...
BA_API int	HttpServerConfig_setMaxSessions (HttpServerConfig *o, U16 size)
	Maximum allowed active HttpSession objects. More...
BA_API void	HttpServer_constructor (HttpServer *, SoDisp *, HttpServerConfig *)
	Initialize a server in caller-provided storage (first argument), using a required borrowed dispatcher (second argument) and optional configuration (third argument). More...
BA_API void	HttpServer_destructor (HttpServer *o)
	Stop using the server before destruction. More...
BA_API int	HttpServer_insertRootDir (HttpServer *o, HttpDir *dir)
	Insert a root directory node. More...
BA_API int	HttpServer_insertDir (HttpServer *o, const char *virtualDirRootPath, HttpDir *dir)
	Insert a directory node into the virtual file system. More...
BA_API int	HttpServer_insertCSP (HttpServer *o, CspInit cspInit, const char *virtualDirRootPath, struct CspReader *reader)
	Insert and initialize a CSP Virtual Directory. More...
BA_API const char *	HttpServer_getStatusCode (int code)
	Return a short description for common HTTP error codes. More...
BA_API HttpSession *	HttpServer_getSession (HttpServer *o, U32 id)
	Returns the HttpSession associated with id or NULL if not found. More...
BA_API void	HttpServer_set404Page (HttpServer *o, const char *page404)
	Set a more user friendly 404 page. More...

Macro Definition Documentation

httpFormUnescape

#define httpFormUnescape

(

s

)

httpUnescapeInternal(s,TRUE)

Decode form escapes in place, also replacing plus with space.

Parameters

s	Required writable NUL-terminated string.

Returns

Last decoded character, or NULL on rejection. See httpUnescapeInternal.

httpUnescape

#define httpUnescape

(

s

)

httpUnescapeInternal(s,FALSE)

Decode URL escapes in place.

See httpUnescapeInternal for errors.

Parameters

s	Required writable NUL-terminated string.

Returns

Last decoded character, or NULL on rejection; not the terminating NUL.

Typedef Documentation

HttpInData

typedef struct HttpInData HttpInData

The web-server "Request Data" container.

HttpParameter

typedef struct HttpParameter HttpParameter

A persistent container object for HTTP parameters.

The parameters in an HttpRequest object are valid only for the duration of the call. The HttpParameter is a container object for the parameters. One can clone the parameters in the request object and save the parameters in an HttpParameter object.

C example:

HttpParameter* param=
  HttpParameter_clone(
     baMalloc(HttpParameter_calculateSize(request) + sizeof(HttpParameter)),
     request);
if(param)
{
   // Use the copied parameters, then release their allocation.
   baFree(param);
}

C++ example:

HttpParameter* param=
  HttpParameter::clone(
     baMalloc(HttpParameter::calculateSize(request) + sizeof(HttpParameter)),
     request);
if(param)
{
   // Use the copied parameters, then release their allocation.
   baFree(param);
}

All parameters are contained within one memory unit and one can simply call baFree(param) when the object is no longer needed.

You use the HttpParameterIterator for iterating the elements in the object.

C example:

HttpParameterIterator i;
HttpParameter* param=
  HttpParameter_clone(baMalloc(HttpParameter_calculateSize(req) + sizeof(HttpParameter)), req);
if(param)
{
   HttpParameterIterator_constructor2(&i, param);
   for(;
      HttpParameterIterator_hasMoreElements(&i) ;
      HttpParameterIterator_nextElement(&i))
   {
      HttpTrace_printf(0,"Param:  %s = %s\n", i.name, i.value);
   }
   baFree(param);
}

C++ Example: See HttpParameterIterator.

Function Documentation

httpEscape()

BA_API char * httpEscape	(	char *	out,
		const char *	in
	)

Encodes characters that cannot be in a http URL.

Parameters

out	Required writable buffer of at least 3*strlen(in)+1 bytes.
in	Required NUL-terminated source; do not overlap output storage.

Returns

Pointer to the output's terminating NUL. No error/size check occurs. Only the implementation's reserved-character set is encoded; this is not general Unicode URL normalization.

httpFmtDate()

BA_API void httpFmtDate	(	char *	buf,
		U16	bufLen,
		BaTime	t
	)

Format an HTTP date in GMT.

Parameters

buf	Required writable output storage.
bufLen	Capacity including NUL; use at least 30 bytes for a four-digit year.
t	Unix time in seconds. No length/status is returned; an insufficient buffer truncates the text.

HttpParameter_calculateSize()

BA_API U32 HttpParameter_calculateSize

(

struct HttpRequest *

req

)

Calculate the HttpParameter size.

Parameters

req	Required live request.

Returns

Bytes for a clone, or zero when no parameters exist. For an empty clone, still provide at least sizeof(HttpParameter) bytes.

HttpParameter_clone()

BA_API HttpParameter * HttpParameter_clone	(	void *	buf,
		struct HttpRequest *	req
	)

Copy HTTP parameters to buf and return as a HttpParameter object.

Parameters

buf	Writable, suitably aligned storage of at least calculateSize(req) bytes, and at least sizeof(HttpParameter) even for an empty request. NULL is accepted and returns NULL; no allocation occurs here.
req	Required live request; strings are copied.

Returns

buf as a container pointer, or NULL for NULL buf. The clone is independent of the request. The caller retains allocation ownership.

HttpParameter_getParameter()

BA_API const char * HttpParameter_getParameter	(	HttpParameter *	o,
		const char *	paramName
	)

Returns the value of a request parameter as a const char*, or null if the parameter does not exist.

Request parameters are extra information sent with the request, which are contained in the query string or posted form data.

If you use this method with a multivalued parameter, the value returned is equal to the first value in a HttpParameterIterator.

Parameters

paramName

Required NUL-terminated, case-sensitive parameter name.

Returns

Borrowed value in this container, or NULL when absent; valid until the container storage is released.

Parameters

o	Required cloned parameter container.

httpUnescapeInternal()

BA_API char * httpUnescapeInternal	(	char *	from,
		BaBool	isForm
	)

Decode percent followed by two hex digits in place.

Parameters

from	Required writable NUL-terminated input/output string.
isForm	Nonzero converts plus to space and permits percent-encoded control characters except NUL. Zero leaves plus unchanged and rejects them. Raw control characters, encoded NUL, and malformed escapes are rejected.

Returns

Last character before the NUL terminator on success, or NULL on error; input can already be partly changed on error. Empty output has no last character: do not dereference or use that result as a buffer address.