This section contains global and lifecycle functions. More...

Macros
#define	dvDefaultConnectTimeoutSeconds 8
	The default number of seconds to wait for a connection. More...

#define	dvDefaultSecretPlaceHolder "^^^SECRET^^^"

Typedefs
typedef void *	dvCtx

typedef int32_t(*	dvSetHeaderFn) (void ctx, const char name, const char *value)

typedef int32_t(*	dvHeaderCb) (void usrCtx, dvSetHeaderFn setHeader, void headerCtx)

typedef int32_t(*	dvSetPostFn) (void ctx, const char name, void *buf, size_t len)

typedef int32_t(*	dvPostCb) (void usrCtx, dvSetPostFn setPostField, void postCtx)

Enumerations
enum	dvCtxOpt { DV_PROXY = (uint32_t)57 , DV_PROXY_USER , DV_PROXY_PASS , DV_SERVICE_URL , DV_APP_ID , DV_CONNECT_TIMEOUT , DV_APPNAME , DV_APPVERSION , DV_CERT_PATH , DV_SECRET , DV_SECRET_PLACE_HOLDER , DV_SKIP_CERT_CHECK , DV_CURL_LOGGING }
	Constants used to set DataVaccinator Client context parameters. More...

Functions
DVAPI int32_t	dvNew (dvCtx dc, const char serviceUrl, const char appId, KvStore cache)

DVAPI void	dvFree (dvCtx dc)

DVAPI int32_t	dvSetHeaderCb (dvCtx dc, dvHeaderCb callback, void *cbCtx)

DVAPI int32_t	dvSetPostCb (dvCtx dc, dvPostCb callback, void *cbCtx)

DVAPI const char *	dvVersion (void)
	Returns the build version of this package. More...

DVAPI void	dvSetCleanLogger (ruLogFunc logger, uint32_t logLevel, perm_ptr userData)
	Sets the global logging function for this process. More...

DVAPI int	dvSetProp (dvCtx dc, enum dvCtxOpt opt, const char *value)
	Sets a DataVaccinator Client context dvCtxOpt option. More...

DVAPI const char *	dvLastError (void)
	Returns an English textual representation of the last error this thread generated. More...

Detailed Description

This section contains global and lifecycle functions.

Macro Definition Documentation

◆ dvDefaultConnectTimeoutSeconds

#define dvDefaultConnectTimeoutSeconds 8

The default number of seconds to wait for a connection.

◆ dvDefaultSecretPlaceHolder

#define dvDefaultSecretPlaceHolder "^^^SECRET^^^"

The default place holder for any secret specified in dvSetProp with DV_SECRET when DV_SECRET_PLACE_HOLDER has not been specified.

Typedef Documentation

◆ dvCtx

typedef void* dvCtx

Opaque pointer to a datavaccinator object.

◆ dvHeaderCb

typedef int32_t(* dvHeaderCb) (void *usrCtx, dvSetHeaderFn setHeader, void *headerCtx)

Interface of function to be called when it's time to set request headers.

Parameters

usrCtx	Opaque context passed as cbCtx to the dvSetHeaderCb function.
setHeader	The dvSetHeaderFn function to call in order to set the desired headers.
headerCtx	Opaque context to be passed as ctx to the given dvSetHeaderFn function.

Returns: RUE_OK on success or error code which will cause the request to be aborted.

◆ dvPostCb

typedef int32_t(* dvPostCb) (void *usrCtx, dvSetPostFn setPostField, void *postCtx)

Interface of function to be called when it's time to set the post fields.

This function can be used to send additional post fields and their associated values to a Service Provider in order to facilitate their particular functionality.

The usage of this callback is subject to the following rules:

The use of the post field json is reserved for the data that is sent to the DataVaccinator Vault service. Attempting to set the post value of json will result in a RUE_INVALID_PARAMETER error.
Be sure to post SID in sid and SPW in spwd if you are interfacing with the DataVaccinator Vault directly.

Parameters

usrCtx	Opaque context passed as cbCtx to the dvSetPostCb function.
setPostField	The dvSetPostFn function to call in order to set the desired post fields.
postCtx	Opaque context to be passed as ctx to the given dvSetPostFn function.

Returns: RUE_OK on success or error code which will cause the request to be aborted.

◆ dvSetHeaderFn

typedef int32_t(* dvSetHeaderFn) (void *ctx, const char *name, const char *value)

Header setter function interface. When this function is called a header is set or removed. If a header matches a header that is already set, the given header takes precedence. To remove an existing header set its name with a null value. To set an empty header set its name with the value of an empty string. The header name must not include a colon. The caller is responsible for header encoding. The header value must not include line endings such as CRLF.

Parameters

ctx	Opaque context to be passed to the function.
name	Name of the header to be set. Must only persist for the duration of this function call.
value	Value of the header in unencoded format. Must only persist for the duration of this function call.

Returns: RUE_OK on success or an error code.

◆ dvSetPostFn

typedef int32_t(* dvSetPostFn) (void *ctx, const char *name, void *buf, size_t len)

Post field setter function interface.

Parameters

ctx	Opaque context to be passed to the function.
name	Name of the header to be set. Must only persist for the duration of this function call.
buf	Data for the value of the field in unencoded format. Must only persist for the duration of this function call.
len	Length of the given buf parameter.

Returns: RUE_OK on success or an error code.

Enumeration Type Documentation

◆ dvCtxOpt

enum dvCtxOpt

Constants used to set DataVaccinator Client context parameters.

Enumerator
DV_PROXY	Proxy URL in the form of protocol://hostname:port
DV_PROXY_USER	Proxy username
DV_PROXY_PASS	Proxy password
DV_SERVICE_URL	The service provider URL
DV_APP_ID	The app-id
DV_CONNECT_TIMEOUT	Timeout in seconds used for network connections. Defaults to vaccinator.
DV_APPNAME	The name this client claims to be during connect. Defaults to dvDefaultConnectTimeoutSeconds
DV_APPVERSION	The version this client claims to be during connect. Defaults to 1.1.0.
DV_CERT_PATH	File path to certificate authority file or directory.
DV_SECRET	A secret to replace in the logs when calling ruVerbLogf type functions. This happens when the logger is initialized by calling dvSetCleanLogger. The secret is replaced with whatever the value of DV_SECRET_PLACE_HOLDER is at the time of this call, not at the time the log call.
DV_SECRET_PLACE_HOLDER	The place holder that will replace a given DV_SECRET in a log cleaned using ruVerbLogf. When this has not been set or set to NULL, it is replaced with dvDefaultSecretPlaceHolder instead. This value is not thread safe and it is copied when dvSetProp is called with DV_SECRET, so it may be set to various values for given secrets.
DV_SKIP_CERT_CHECK	This will disable SSL certificate verification when set to non 0. Helpful when developing.
DV_CURL_LOGGING	This will turn on cURL debug logging e when set to non 0 and the general log level is at RU_LOG_VERB.

Function Documentation

◆ dvFree()

DVAPI void dvFree ( dvCtx dc )

Frees a dvCtx that was created with dvNew when it is no longer needed.

Parameters

dc	The dvCtx to free.

◆ dvLastError()

DVAPI const char* dvLastError ( void )

Returns an English textual representation of the last error this thread generated.

Note, not all functions use this, so this function should only be called after a function that does use it is called, else misleading information will appear.

Returns: Last error message. Must be copied if it is to persist.

◆ dvNew()

DVAPI int32_t dvNew	(	dvCtx *	dc,
		const char *	serviceUrl,
		const char *	appId,
		KvStore *	cache
	)

Creates a new Datavaccinator context object.

Parameters

dc	Where the new dvCtx will be stored. Free with dvFree.
serviceUrl	The URL of the Service Provider that this DataVaccinator Client talks to. This may also be the DataVaccinator Vault URL directly if you use the dvSetPostCb to supply the required SID / SPW credentials.
appId	This is the end users application password for data encryption.
cache	A KvStore instance that can be used as a local data cache. The caller must preserve the KvStore instance for the life of this context and may/should free it afterwards. If NULL no caching will be done.

Returns: RUE_OK on success or an error code.

◆ dvSetCleanLogger()

DVAPI void dvSetCleanLogger	(	ruLogFunc	logger,
		uint32_t	logLevel,
		perm_ptr	userData
	)

Sets the global logging function for this process.

This function is like ruSetLogger with the difference that log data has its credentials sanitized out. This is the preferred alternative to ruSetLogger when using the DataVaccinator Client. You can specify credentials to be sanitized out by calling dvSetProp with DV_SECRET.

Parameters

logger	Logging function that will be called with messages.
logLevel	Loglevel to determine what gets logged.
userData	Opaque custom user data that will be passed to the ruLogFunc implementation.

◆ dvSetHeaderCb()

DVAPI int32_t dvSetHeaderCb	(	dvCtx	dc,
		dvHeaderCb	callback,
		void *	cbCtx
	)

Sets the function to call when the request headers are being written.

Parameters

dc	The dvCtx to work with.
callback	The dvHeaderCb to call.
cbCtx	An optional context that will be passed into the dvHeaderCb as the usrCtx parameter.

Returns: RUE_OK on success or an error code.

Example

int32_t headerCb(void* usrCtx, dvSetHeaderFn setHeader, void* headerCtx) {
    return setHeader(headerCtx, "Cache-Control", "max-age=60");
}
 
int main ( int argc, char **argv ) {
    ...
    dvSetHeaderCb(ctx, &headerCb, NULL);
    ...
}

Remarks: Error handling has been omitted for brevity.

◆ dvSetPostCb()

DVAPI int32_t dvSetPostCb	(	dvCtx	dc,
		dvPostCb	callback,
		void *	cbCtx
	)

Sets the function to call when the post fields are being written.

Parameters

dc	The dvCtx to work with.
callback	The dvPostCb to call.
cbCtx	An optional context that will be passed into the dvPostCb as the usrCtx parameter.

Returns: RUE_OK on success or an error code.

Example

int32_t postCb(void* usrCtx, dvSetPostFn setPostField, void* postCtx) {
    char* myvalue = (char*) usrCtx;
    return setPostField(postCtx, "myfield", (void*)myvalue, strlen(myvalue));
}
 
int main ( int argc, char **argv ) {
    ...
    const char *myvalue = "my special value";
    dvSetPostCb(ctx, &postCb, (void*)myvalue);
    ...
}

Remarks: Error handling has been omitted for brevity.

◆ dvSetProp()

DVAPI int dvSetProp	(	dvCtx	dc,
		enum dvCtxOpt	opt,
		const char *	value
	)

Sets a DataVaccinator Client context dvCtxOpt option.

Parameters

[in]	dc	The dvCtx to set the option for.
[in]	opt	The dvCtxOpt option to set.
[in]	value	The value to set it to or NULL to unset it. The given string will be copied.

Returns: A rferrors status of the operation.

◆ dvVersion()

DVAPI const char* dvVersion ( void )

Returns the build version of this package.

This is the actual build version and should not be confused with DV_APPVERSION which is sent to the service providers.

Returns: Version of this package. This string is static and must not be freed.

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ dvDefaultConnectTimeoutSeconds

◆ dvDefaultSecretPlaceHolder

Typedef Documentation

◆ dvCtx

◆ dvHeaderCb

◆ dvPostCb

◆ dvSetHeaderFn

◆ dvSetPostFn

Enumeration Type Documentation

◆ dvCtxOpt

Function Documentation

◆ dvFree()

◆ dvLastError()

◆ dvNew()

◆ dvSetCleanLogger()

◆ dvSetHeaderCb()

◆ dvSetPostCb()

◆ dvSetProp()

◆ dvVersion()