Pix Module

Detailed description

Operations destined for Pix of the SPI (Instant Payments System).

See HSM technical documentation about operating details, specifications used, licenses and module trade name.

Best practices

General

1. Reuse sessions (benefit from session caching). Utilize the HSM session cache to improve performance by reusing both HSM and HTTP sessions. In this scenario, it is recommended to open a session, perform the desired operations, and then close it; this allows the session to be quickly reused, thereby reducing idle time.
2. Ensure session closure. Closing sessions guarantees resource release, both on the HSM and the client. Ensure that sessions are closed even for operations with a return code other than success.
3. Utilize concurrent sessions. Using concurrent/parallel sessions with the HSM helps extract maximum performance. Care should be taken to avoid an excessive number of sessions with HSMs, to prevent unnecessary resource consumption. The throughput curve tends to rise and then plateau.

HTTP requests Pix

1. Reuse the handle ` Pix`. The handle created by ` DPIXOpenHandle() ` stores the credentials and object identifiers and does not depend on an open HSM session. Keep the handle for the duration of the application instead of opening and closing it with each request.
2. Open one handle per thread. A handle can be used by multiple threads, but never simultaneously. In the default mode, this does not imply one connection per handle: all threads share the HTTP connection cache.
3. Set a connection limit only when the environment requires it. The default is unlimited, and the cache grows as application concurrency increases. Configure HSM_PIX_POOL_MAX_HANDLES when there is a restriction on the number of simultaneous connections to the peer. In this case, measure the cache counters first (DPIXGetCacheParam()) and set the limit based on the highest observed value, rather than estimating it.
4. Clear the cache when the environment requires it, to trigger a refresh of the objects. HSM objects are read during the handshake, so connections that are already open continue to use the previous objects until they are reestablished. If the update needs to take effect immediately, calling `DPIXSetCacheParam()` with `PIXCP_CLEAR ` causes the next request to reconnect and re-read the objects.

Important Configurations

General

1. Set the HSM connection timeouts. When the HSM timeout is not set, the default is that of the operating system. In the event of a connection failure, the application may wait too long. It is important to ALWAYS set the HSM's send and receive timeouts. Other connection parameters can be found here.

HTTP requests Pix

1. Define the HTTP operation timeouts. If not defined, the default HTTP operation timeout is unlimited. In the event of an HTTP connection failure, the application may wait indefinitely. It is ALWAYS important to define the timeout for HTTP request calls.

Functions
int AAP_API	DPIXSign (HSESSIONCTX hSession, const char *szKeyId, const char *szCertId, DWORD dwFlags, DWORD dwSizeUnsignedPixEnvelope, BYTE *pbUnsignedPixEnvelope, DWORD *pdwSizeSignedPixEnvelope, BYTE **ppbSignedPixEnvelope)
	Digitally signs an XML in ISO 20.022 format following the PIX standard defined in the SPI (Instant Payment System).
int AAP_API	DPIXVerify (HSESSIONCTX hSession, const char *szChainId, const char *szCRL, DWORD dwFlags, DWORD dwSizeSignedPixEnvelope, BYTE *pbSignedPixEnvelope)
	Checks the signature of a digitally signed XML document in ISO 20.022 format following the PIX standard defined in the SPI (Instant Payment System).
int AAP_API	DPIXDictSign (HSESSIONCTX hSession, const char *szKeyId, const char *szCertId, DWORD dwFlags, DWORD dwSizeUnsignedDictEnvelope, BYTE *pbUnsignedDictEnvelope, DWORD *pdwSizeSignedDictEnvelope, BYTE **ppbSignedDictEnvelope)
	Digitally signs an XML in XMLDSig format, following the DICT standard defined in the SPI (Instant Payment System).
int AAP_API	DPIXDictVerify (HSESSIONCTX hSession, const char *szChainId, const char *szCRL, DWORD dwFlags, DWORD dwSizeSignedDictEnvelope, BYTE *pbSignedDictEnvelope)
	Verifies the signature of a digitally signed XML document in XMLDSig format, following the DICT standard defined in the SPI (Instant Payment System).
int AAP_API	DPIXJWSSign (HSESSIONCTX hSession, const char *szKeyId, DWORD dwFlags, DWORD dwHeaderLen, BYTE *pbHeader, DWORD dwPayloadLen, BYTE *pbPayload, DWORD *pdwJWSLen, BYTE *pbJWS)
	Makes a JWS RFC 7515 signature following the PIX standard defined in the SPI (Instant Payment System).
int AAP_API	DPIXJWSCheck (HSESSIONCTX hSession, const char *szChain, const char *szCRL, DWORD dwJWSLen, BYTE *pbJWS, DWORD dwFlags, DWORD *pdwHeaderLen, BYTE *pbHeader, DWORD *pdwPayloadLen, BYTE *pbPayload)
	Validates an RFC 7515 signed JWS following the PIX standard defined in the SPI (Instant Payment System).
int AAP_API	DPIXPost (HSESSIONCTX hSession, const char *szKeyId, const char *szCertId, const char *szPixCertChainId, const char *szURL, DWORD dwCountRequestHeaderList, const char *pszRequestHeaderList[], DWORD dwSizeRequestData, BYTE *pbRequestData, DWORD dwTimeOut, DWORD *pdwSizeResponseHeaders, BYTE **ppbResponseHeaders, DWORD *pdwSizeResponseBody, BYTE **ppbResponseBody, DWORD dwParam)
	It makes a secure HTTP POST request following the PIX standard defined in SPI (Instant Payment System).
int AAP_API	DPIXPut (HSESSIONCTX hSession, const char *szKeyId, const char *szCertId, const char *szPixCertChainId, const char *szURL, DWORD dwCountRequestHeaderList, const char *pszRequestHeaderList[], DWORD dwSizeRequestData, BYTE *pbRequestData, DWORD dwTimeOut, DWORD *pdwSizeResponseHeaders, BYTE **ppbResponseHeaders, DWORD *pdwSizeResponseBody, BYTE **ppbResponseBody, DWORD dwParam)
	It makes a secure HTTP PUT request following the PIX standard defined in the SPI (Instant Payment System).
int AAP_API	DPIXGet (HSESSIONCTX hSession, const char *szKeyId, const char *szCertId, const char *szPixCertChainId, const char *szURL, DWORD dwCountRequestHeaderList, const char *pszRequestHeaderList[], DWORD dwTimeOut, DWORD *pdwSizeResponseHeaders, BYTE **ppbResponseHeaders, DWORD *pdwSizeResponseBody, BYTE **ppbResponseBody, DWORD dwParam)
	It makes a secure HTTP GET request following the PIX standard defined in the SPI (Instant Payment System).
int AAP_API	DPIXDelete (HSESSIONCTX hSession, const char *szKeyId, const char *szCertId, const char *szPixCertChainId, const char *szURL, DWORD dwCountRequestHeaderList, const char *pszRequestHeaderList[], DWORD dwTimeOut, DWORD *pdwSizeResponseHeaders, BYTE **ppbResponseHeaders, DWORD *pdwSizeResponseBody, BYTE **ppbResponseBody, DWORD dwParam)
	It makes a secure HTTP DELETE request following the PIX standard defined in SPI (Instant Payment System).
int AAP_API	DPIXOpenHandle (HPIXSESSIONCTX *phPIXSession, const char *szKeyId, const char *szCertId, const char *szPIXCertChainId, DWORD dwParam, BYTE *pbData, DWORD dwDataLen, DWORD dwFlags, DWORD dwPixFlags)
	Creates a ` PIX` handle, which encapsulates a persistent HTTP connection and the TLS material (certificate, chain, and key) used in the mTLS tunnel.
int AAP_API	DPIXCloseHandle (HPIXSESSIONCTX *phPIXSession, DWORD dwReserved)
	Destroys a handle PIX created by DPIXOpenHandle(), clearing the credentials stored in it from memory.
int AAP_API	DPIXGetHandleParam (HPIXSESSIONCTX hPIXSession, DWORD dwParam, BYTE *pbData, DWORD *pdwDataLen, DWORD dwReserved)
	Retrieves information and counters from a ` PIX` handle.
int AAP_API	DPIXSetCacheParam (DWORD dwParam, BYTE *pbData, DWORD dwDataLen, DWORD dwReserved)
	Configures the HTTP session cache for PIX, which is used by the DPIXPost(), DPIXPut(), DPIXGet(), and DPIXDelete() functions.
int AAP_API	DPIXGetCacheParam (DWORD dwParam, BYTE *pbData, DWORD *pdwDataLen, DWORD dwReserved)
	Restores the configuration and counters for the HTTP session cache in PIX.
int AAP_API	DPIXRequest (HPIXSESSIONCTX hPIXSession, const PIX_REQUEST *pstRequest, PIX_RESPONSE *pstResponse, DWORD dwReserved)
	Makes an HTTP request using the handle ` PIX`, for any method.
int AAP_API	DPIXFreeResponse (PIX_RESPONSE *pstResponse)
	Frees the buffers of a PIX_RESPONSE filled by DPIXRequest().

Functions

DPIXSign()

int AAP_API DPIXSign	(	HSESSIONCTX	hSession,
		const char *	szKeyId,
		const char *	szCertId,
		DWORD	dwFlags,
		DWORD	dwSizeUnsignedPIXEnvelope,
		BYTE *	pbUnsignedPIXEnvelope,
		DWORD *	pdwSizeSignedPIXEnvelope,
		BYTE **	ppbSignedPIXEnvelope )

#include <dinamo.h>

Digitally signs an XML in ISO 20.022 format following the PIX standard defined in the SPI (Instant Payment System).

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szKeyId	Name of the private key used for signing. Corresponds to a CPIA certificate.
[in]	szCertId	Name of the digital certificate used for signing. This is the PSP's Digital Certificate registered with SPI for signing, also known as CPIA or CERTPIA.
[in]	dwFlags	Signing options. Pass 0. If additional options are required, the following values are accepted. Value Meaning PIX_SIGN_RNS Enables the use of relative namespaces.
[in]	dwSizeUnsignedPIXEnvelope	Size, in bytes, of the original XML in pbUnsignedPIXEnvelope.
[in]	pbUnsignedPIXEnvelope	Buffer containing the original XML.
[out]	pdwSizeSignedPIXEnvelope	Pointer to the size of the signed XML, in bytes. When the function returns, this parameter will contain the size of the data stored in ppbSignedPIXEnvelope.
[out]	ppbSignedPIXEnvelope	Pointer to a pointer returning the signed XML. Memory allocation is handled internally. The calling application is responsible for freeing the allocated memory using the DFree() API. Refer to the remarks for further information.

Returns

0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.

Notes

For performance reasons, we recommend using the signature tag with a complete closing, as shown below.

<Sgntr></Sgntr>

The tag with a simple closing is also accepted; see below.

<Sgntr/>

Examples

sign_verify_pix.c.

DPIXVerify()

int AAP_API DPIXVerify	(	HSESSIONCTX	hSession,
		const char *	szChainId,
		const char *	szCRL,
		DWORD	dwFlags,
		DWORD	dwSizeSignedPIXEnvelope,
		BYTE *	pbSignedPIXEnvelope )

#include <dinamo.h>

Checks the signature of a digitally signed XML document in ISO 20.022 format following the PIX standard defined in the SPI (Instant Payment System).

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szChainId	Name of the PKCS#7 chain (stored internally in the HSM) of the certificate used in the signature. The chain must be complete, from the root CA to the certificate used in the signature. This formatting is necessary because the XML message from Pix does not contain the certificate used in the signature. Optionally, only the X.509 certificate used to sign can be passed instead of the complete chain. As of version 5.0.23 of the HSM firmware, it is possible to use a PKCS#7 object that contains several chains. It is important to note that in the case of an HSM PKCS#7 object containing multiple chains, the presence of an expired certificate in any of the chains will generate a valid signature return code with an expired certificate (non-zero code) in the verification, even if the signature was made with a certificate from a non-expired chain; it is up to the application to handle this correctly according to local policy.
[in]	szCRL	Certificate Revocation List (CRL) Name – stored internally in the HSM – where the digital certificate will be verified. NULL can be passed to indicate that no CRL is available for verification.
[in]	dwFlags	Reserved for future use (must be 0).
[in]	dwSizeSignedPIXEnvelope	Size, in bytes, of the XML signed in pbSignedPIXEnvelope.
[in]	pbSignedPIXEnvelope	Signed XML.

Returns

0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.

Examples

sign_verify_pix.c.

DPixDictSign()

int AAP_API DPIXDictSign	(	HSESSIONCTX	hSession,
		const char *	szKeyId,
		const char *	szCertId,
		DWORD	dwFlags,
		DWORD	dwSizeUnsignedDictEnvelope,
		BYTE *	pbUnsignedDictEnvelope,
		DWORD *	pdwSizeSignedDictEnvelope,
		BYTE **	ppbSignedDictEnvelope )

#include <dinamo.h>

Digitally signs an XML in XMLDSig format, following the DICT standard defined in the SPI (Instant Payment System).

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szKeyId	Name of the private key used for signing. Corresponds to a CPIA certificate.
[in]	szCertId	Name of the digital certificate used for signing. This is the PSP's Digital Certificate registered with SPI for signing, also known as CPIA or CERTPIA.
[in]	dwFlags	Reserved for future use (must be 0).
[in]	dwSizeUnsignedDictEnvelope	Size, in bytes, of the original XML in pbUnsignedDictEnvelope.
[in]	pbUnsignedDictEnvelope	Buffer containing the original XML.
[out]	pdwSizeSignedDictEnvelope	Pointer to the size of the signed XML, in bytes. When the function returns, this parameter will contain the size of the data stored in ppbSignedDictEnvelope.
[out]	ppbSignedDictEnvelope	Pointer to a pointer returning the signed XML. Memory allocation is handled internally. The calling application is responsible for freeing the allocated memory using the DFree() API. Refer to the remarks for further information.

Returns

0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.

Notes

Do not include the signature tag; it will be added automatically.

Examples

sign_verify_dict.c.

DPixDictVerify()

int AAP_API DPIXDictVerify	(	HSESSIONCTX	hSession,
		const char *	szChainId,
		const char *	szCRL,
		DWORD	dwFlags,
		DWORD	dwSizeSignedDictEnvelope,
		BYTE *	pbSignedDictEnvelope )

#include <dinamo.h>

Verifies the signature of a digitally signed XML document in XMLDSig format, following the DICT standard defined in the SPI (Instant Payment System).

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szChainId	Name of the PKCS#7 chain (stored internally in the HSM) of the certificate used in the signature. The chain must be complete, from the root CA to the certificate used in the signature. This formatting is necessary because the XML message from Pix does not contain the certificate used in the signature. Optionally, only the X.509 certificate used to sign can be passed instead of the complete chain. As of version 5.0.23 of the HSM firmware, it is possible to use a PKCS#7 object that contains several chains. It is important to note that in the case of an HSM PKCS#7 object containing multiple chains, the presence of an expired certificate in any of the chains will generate a valid signature return code with an expired certificate (non-zero code) in the verification, even if the signature was made with a certificate from a non-expired chain; it is up to the application to handle this correctly according to local policy.
[in]	szCRL	Certificate Revocation List (CRL) Name – stored internally in the HSM – where the digital certificate will be verified. NULL can be passed to indicate that no CRL is available for verification.
[in]	dwFlags	Reserved for future use (must be 0).
[in]	dwSizeSignedDictEnvelope	Size, in bytes, of the signed XML in pbSignedDictEnvelope.
[in]	pbSignedDictEnvelope	Signed XML.

Returns

0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.

Examples

sign_verify_dict.c.

DPixJWSSign()

int AAP_API DPIXJWSSign	(	HSESSIONCTX	hSession,
		const char *	szKeyId,
		DWORD	dwFlags,
		DWORD	dwHeaderLen,
		BYTE *	pbHeader,
		DWORD	dwPayloadLen,
		BYTE *	pbPayload,
		DWORD *	pdwJWSLen,
		BYTE *	pbJWS )

#include <dinamo.h>

Makes a JWS RFC 7515 signature following the PIX standard defined in the SPI (Instant Payment System).

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szKeyId	Name of the private key used for signing. As defined in the PIX
[in]	dwFlags	Signature options. Must be set to 0.
[in]	dwHeaderLen	Size, in bytes, of the JWS Header in pbHeader.
[in]	pbHeader	JWS Header for signature. At least the header parameter alg must be provided. Accepted values for alg. Value Meaning RS256 RSA 2048 PKCS#1v5 RS384 RSA 3072 PKCS#1v5 RS512 RSA 4096 PKCS#1v5 PS256 RSA 2048 PSS PS384 RSA 3072 PSS PS512 RSA 4096 PSS ES256 ECC SECP256R1 ES384 ECC SECP384R1 ES512 ECC SECP521R1
[in]	dwPayloadLen	Size, in bytes, of the JWS Payload in pbPayload.
[in]	pbPayload	Buffer containing the JWS Payload for signing.
[in,out]	pdwJWSLen	Pointer to the size of the pbJWS buffer, in bytes. When the function returns, this parameter will contain the size of the data stored in pbJWS.
[out]	pbJWS	Buffer that will contain the signed JWS. If NULL is passed, the API will return 0 and pdwJWSLen will contain the estimated required size of pbJWS.

Returns

0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.

Notes

Uses the Compact Serialization format described in Section-3.1 of RFC 7515.

Examples

sign_check_pix_jws.c.

DPIXJWSCheck()

int AAP_API DPIXJWSCheck	(	HSESSIONCTX	hSession,
		const char *	szChain,
		const char *	szCRL,
		DWORD	dwJWSLen,
		BYTE *	pbJWS,
		DWORD	dwFlags,
		DWORD *	pdwHeaderLen,
		BYTE *	pbHeader,
		DWORD *	pdwPayloadLen,
		BYTE *	pbPayload )

#include <dinamo.h>

Validates an RFC 7515 signed JWS following the PIX standard defined in the SPI (Instant Payment System).

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szChain	Name of the PKCS#7 chain (stored internally in the HSM) of the certificate used in the signature. The chain must be complete, from the root CA to the certificate used in the signature. This formatting is necessary because the XML message from Pix does not contain the certificate used in the signature. Optionally, only the X.509 certificate used to sign can be passed instead of the complete chain. As of version 5.0.23 of the HSM firmware, it is possible to use a PKCS#7 object that contains several chains. It is important to note that in the case of an HSM PKCS#7 object containing multiple chains, the presence of an expired certificate in any of the chains will generate a valid signature return code with an expired certificate (non-zero code) in the verification, even if the signature was made with a certificate from a non-expired chain; it is up to the application to handle this correctly according to local policy.
[in]	szCRL	Certificate Revocation List (CRL) Name – stored internally in the HSM – where the digital certificate will be verified. NULL can be passed to indicate that no CRL is available for verification.
[in]	dwJWSLen	Size, in bytes, of the JWS signature in pbJWS.
[in]	pbJWS	Signed JWS.
[in]	dwFlags	Validation options. Must be passed as 0.
[in,out]	pdwHeaderLen	Pointer to the size of the pbHeader buffer, in bytes. When the function returns, this parameter will contain the size of the data stored in pbHeader.
[out]	pbHeader	Buffer that will contain the JWS Header. If NULL is passed, the API will return 0 and pdwHeaderLen will contain the estimated required size of pbHeader.
[in,out]	pdwPayloadLen	Pointer to the size of the pbPayload buffer, in bytes. When the function returns, this parameter will contain the size of the data stored in pbPayload.
[out]	pbPayload	Buffer that will contain the JWS Payload. If NULL is passed, the API will return 0 and pdwPayloadLen will contain the estimated required size of pbPayload.

Returns

0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.

Examples

sign_check_pix_jws.c.

DPIXPost()

int AAP_API DPIXPost	(	HSESSIONCTX	hSession,
		const char *	szKeyId,
		const char *	szCertId,
		const char *	szPIXCertChainId,
		const char *	szURL,
		DWORD	dwCountRequestHeaderList,
		const char *	pszRequestHeaderList[],
		DWORD	dwSizeRequestData,
		BYTE *	pbRequestData,
		DWORD	dwTimeOut,
		DWORD *	pdwSizeResponseHeaders,
		BYTE **	ppbResponseHeaders,
		DWORD *	pdwSizeResponseBody,
		BYTE **	ppbResponseBody,
		DWORD	dwParam )

#include <dinamo.h>

It makes a secure HTTP POST request following the PIX standard defined in SPI (Instant Payment System).

Note

Configure timeout settings. Refer to the Best Practices section for more details.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szKeyId	Name of the private key used for tunnel establishment. Corresponds to a CPIC certificate.
[in]	szCertId	Name of the certificate used for tunnel establishment. This is the PSP Digital Certificate registered with SPI for connection, also known as CPIC or CERTPIC.
[in]	szPIXCertChainId	Name of the PKCS#7 string used to check the PIX server (ICOM or DICT). As of version 5.0.23 of the HSM firmware, it is possible to use a PKCS#7 object containing several strings.
[in]	szURL	URL of the server PIX (ICOM or DICT).
[in]	dwCountRequestHeaderList	Number of lines filled in pszRequestHeaderList.
[in]	pszRequestHeaderList	Lines containing the customized HTTP headers that will be used in the request. Can be passed null if you want to use the default header without changes. This option will overwrite the default headers if they overlap. To remove a header, pass the name of the header without a value (e.g. Accept:). To include a header without content, use ; instead of : (e.g. Accept;). Do NOT use CRLF terminators in headers. Passing these terminators may cause unwanted behavior. Formatting will be done internally. This option cannot be used to change the first line of the request (e.g. POST, PUT, GET, DELETE), which is not a header. The corresponding API, described in this manual, must be used. The default initial header includes Host, User-Agent, Accept, Accept-Encoding, Content-Type, Expect and Content-Length.
[in]	dwSizeRequestData	Size of the data passed in pbRequestData.
[in]	pbRequestData	Data sent in the request.
[in]	dwTimeOut	Operation timeout in milliseconds. Can be set to 0 for no timeout.
[out]	pdwSizeResponseHeaders	Pointer that will contain the size of the data stored in the ppbResponseHeaders buffer, in bytes.
[out]	ppbResponseHeaders	Internally allocated buffer that will contain the header returned by the request. The size allocated is defined in pdwSizeResponseHeaders. This pointer must be freed using the DFree() API.
[out]	pdwSizeResponseBody	Pointer that will contain the size of the data stored in the ppbResponseBody buffer, in bytes.
[out]	ppbResponseBody	Internally allocated buffer that will contain the body returned by the request. The allocated size is defined in pdwSizeResponseBody. This pointer must be freed using the DFree() API.
[in]	dwParam	Value Meaning 0 Default option. Does not verify the certificate against the hostname. PIX_VERIFY_HOST_NAME Verifies the certificate against the hostname. PIX_BASIC_HTTP_HEADER Uses the basic initial HTTP header. Includes Host, User-Agent, and Content-Length. PIX_GZIP Performs automatic gzip compression of request data. Automatically includes the necessary headers (Content-Encoding and Accept-Encoding).

Returns

0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.

Notes

It executes a secure request following the PIX standard defined in the SPI in the documents: "Annex IV - Security Manual", "Technical and business specifications of the Brazilian instant payment ecosystem" and "Annex III - Communication Interfaces Manual" defined in the SPI.
The negotiated tunnel is TLS version 1.2 with mutual authentication, using the HTTP protocol version 1.1 with a minimum Cipher Suite of ECDHE-RSA-AES-128-GCM-SHA256.

This API will automatically decompress a response that comes compressed in the gzip standard. If you choose to compress the sending data, the API caller must do so in gzip format.

This request uses the following headers by default.
"Accept-Encoding: gzip"
"User-Agent: DNLC/0.0.0.0", where 0.0.0.0 is the version of the HSM client library used.

Certificate validation with the host name is done by checking that the Common Name field or Subject Alternate Name field of the certificate matches the host name of the URL passed as a parameter.

When making an HTTP request, 2 operations are performed, one to use the HSM objects (private key, certificate and chain, used for tunnel authentication) and the other to open the HTTP session with the HTTP server.
To optimize resources, the session with the HTTP server is kept open and cached; likewise, the session with the HSM is cached by default (the HSM session can optionally be set not to be cached).
The HTTP session is associated with the session opened with the HSM, which means that to reuse an HTTP session you must use the same HSM session that was previously used to open the HTTP session.
The HTTP session is physically closed when the session with the HSM is physically closed.
The HSM session and the HTTP session have thread-session affinity and cannot be used simultaneously by several threads.

Long Polling is adjusted by setting the HTTP operation timeout (POST/GET/DELETE) according to the HTTP server settings.

See also

DFree() DPIXGet() DPIXDelete()

Examples

post_put_get_delete_pix.c.

DPIXPut()

int AAP_API DPIXPut	(	HSESSIONCTX	hSession,
		const char *	szKeyId,
		const char *	szCertId,
		const char *	szPIXCertChainId,
		const char *	szURL,
		DWORD	dwCountRequestHeaderList,
		const char *	pszRequestHeaderList[],
		DWORD	dwSizeRequestData,
		BYTE *	pbRequestData,
		DWORD	dwTimeOut,
		DWORD *	pdwSizeResponseHeaders,
		BYTE **	ppbResponseHeaders,
		DWORD *	pdwSizeResponseBody,
		BYTE **	ppbResponseBody,
		DWORD	dwParam )

#include <dinamo.h>

It makes a secure HTTP PUT request following the PIX standard defined in the SPI (Instant Payment System).

Note

Configure timeout settings. Refer to the Best Practices section for more details.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szKeyId	Name of the private key used for tunnel establishment. Corresponds to a CPIC certificate.
[in]	szCertId	Name of the certificate used for tunnel establishment. This is the PSP Digital Certificate registered with SPI for connection, also known as CPIC or CERTPIC.
[in]	szPIXCertChainId	Name of the PKCS#7 string used to check the PIX server (ICOM or DICT). As of version 5.0.23 of the HSM firmware, it is possible to use a PKCS#7 object containing several strings.
[in]	szURL	URL of the server PIX (ICOM or DICT).
[in]	dwCountRequestHeaderList	Number of lines filled in pszRequestHeaderList.
[in]	pszRequestHeaderList	Lines containing the customized HTTP headers that will be used in the request. Can be passed null if you want to use the default header without changes. This option will overwrite the default headers if they overlap. To remove a header, pass the name of the header without a value (e.g. Accept:). To include a header with no content, use ; instead of : (e.g. Accept;). Do NOT use CRLF terminators in headers. Passing these terminators may cause unwanted behavior. Formatting will be done internally. This option cannot be used to change the first line of the request (e.g. POST, PUT, GET, DELETE), which is not a header. The corresponding API, described in this manual, must be used. The default initial header includes Host, User-Agent, Accept, Accept-Encoding, Expect and Content-Length.
[in]	dwSizeRequestData	Size of the data passed in pbRequestData.
[in]	pbRequestData	Data sent in the request.
[in]	dwTimeOut	Operation timeout in milliseconds. Can be set to 0 for no timeout.
[out]	pdwSizeResponseHeaders	Pointer that will contain the size of the data stored in the ppbResponseHeaders buffer, in bytes.
[out]	ppbResponseHeaders	Internally allocated buffer that will contain the header returned by the request. The size allocated is defined in pdwSizeResponseHeaders. This pointer must be freed using the DFree() API.
[out]	pdwSizeResponseBody	Pointer that will contain the size of the data stored in the ppbResponseBody buffer, in bytes.
[out]	ppbResponseBody	Internally allocated buffer that will contain the body returned by the request. The allocated size is defined in pdwSizeResponseBody. This pointer must be freed using the DFree() API.
[in]	dwParam	Value Meaning 0 Default option. Does not verify the certificate against the hostname. PIX_VERIFY_HOST_NAME Verifies the certificate against the hostname. PIX_BASIC_HTTP_HEADER Uses the basic initial HTTP header. Includes Host, User-Agent, and Content-Length. PIX_GZIP Performs automatic gzip compression of request data. Automatically includes the necessary headers (Content-Encoding and Accept-Encoding).

Returns

0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.

Notes

It executes a secure request following the PIX standard defined in the SPI in the documents: "Annex IV - Security Manual", "Technical and business specifications of the Brazilian instant payment ecosystem" and "Annex III - Communication Interfaces Manual" defined in the SPI.
The negotiated tunnel is TLS version 1.2 with mutual authentication, using the HTTP protocol version 1.1 with a minimum Cipher Suite of ECDHE-RSA-AES-128-GCM-SHA256.

This API will automatically decompress a response that comes compressed in the gzip standard. If you choose to compress the sending data, the API caller must do so in gzip format.

This request uses the following headers by default.
"Accept-Encoding: gzip"
"User-Agent: DNLC/0.0.0.0", where 0.0.0.0 is the version of the HSM client library used.

Certificate validation with the host name is done by checking that the Common Name field or Subject Alternate Name field of the certificate matches the host name of the URL passed as a parameter.

When making an HTTP request, 2 operations are performed, one to use the HSM objects (private key, certificate and chain, used for tunnel authentication) and the other to open the HTTP session with the HTTP server.
To optimize resources, the session with the HTTP server is kept open and cached; likewise, the session with the HSM is cached by default (the HSM session can optionally be set not to be cached).
The HTTP session is associated with the session opened with the HSM, which means that to reuse an HTTP session you must use the same HSM session that was previously used to open the HTTP session.
The HTTP session is physically closed when the session with the HSM is physically closed.
The HSM session and the HTTP session have thread-session affinity and cannot be used simultaneously by several threads.

Long Polling is adjusted by setting the HTTP operation timeout (POST/GET/DELETE) according to the HTTP server settings.

See also

DFree() DPIXPut() DPIXGet() DPIXDelete()

Examples

post_put_get_delete_pix.c.

DPIXGet()

int AAP_API DPIXGet	(	HSESSIONCTX	hSession,
		const char *	szKeyId,
		const char *	szCertId,
		const char *	szPIXCertChainId,
		const char *	szURL,
		DWORD	dwCountRequestHeaderList,
		const char *	pszRequestHeaderList[],
		DWORD	dwTimeOut,
		DWORD *	pdwSizeResponseHeaders,
		BYTE **	ppbResponseHeaders,
		DWORD *	pdwSizeResponseBody,
		BYTE **	ppbResponseBody,
		DWORD	dwParam )

#include <dinamo.h>

It makes a secure HTTP GET request following the PIX standard defined in the SPI (Instant Payment System).

Note

Configure timeout settings. Refer to the Best Practices section for more details.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szKeyId	Name of the private key used for tunnel establishment. Corresponds to a CPIC certificate.
[in]	szCertId	Name of the certificate used for tunnel establishment. This is the PSP Digital Certificate registered with SPI for connection, also known as CPIC or CERTPIC.
[in]	szPIXCertChainId	Name of the PKCS#7 string used to check the PIX server (ICOM or DICT). As of version 5.0.23 of the HSM firmware, it is possible to use a PKCS#7 object containing several strings.
[in]	szURL	URL of the server PIX (ICOM or DICT).
[in]	dwCountRequestHeaderList	Number of lines filled in pszRequestHeaderList.
[in]	pszRequestHeaderList	Lines containing the customized HTTP headers that will be used in the request. Can be passed null if you want to use the default header without changes. This option will overwrite the default headers if they overlap. To remove a header, pass the name of the header without a value (e.g. Accept:). To include a header with no content, use ; instead of : (e.g. Accept;). Do NOT use CRLF terminators in headers. Passing these terminators may cause unwanted behavior. Formatting will be done internally. This option cannot be used to change the first line of the request (e.g. POST, PUT, GET, DELETE), which is not a header. The corresponding API, described in this manual, must be used. The default initial header includes Host, User-Agent, Accept, Accept-Encoding.
[in]	dwTimeOut	Operation timeout in milliseconds. Can be set to 0 for no timeout.
[out]	pdwSizeResponseHeaders	Pointer that will contain the size of the data stored in the ppbResponseHeaders buffer, in bytes.
[out]	ppbResponseHeaders	Internally allocated buffer that will contain the header returned by the request. The size allocated is defined in pdwSizeResponseHeaders. This pointer must be freed using the DFree() API.
[out]	pdwSizeResponseBody	Pointer that will contain the size of the data stored in the ppbResponseBody buffer, in bytes.
[out]	ppbResponseBody	Internally allocated buffer that will contain the body returned by the request. The allocated size is defined in pdwSizeResponseBody. This pointer must be freed using the DFree() API.
[in]	dwParam	Value Meaning 0 Default option. Does not verify the certificate against the hostname. PIX_VERIFY_HOST_NAME Verifies the certificate against the hostname. PIX_BASIC_HTTP_HEADER Uses the basic initial HTTP header. Includes Host and User-Agent. PIX_GZIP Includes the Accept-Encoding: gzip header if the basic header is enabled.

Returns

0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.

Notes

It executes a secure request following the PIX standard defined in the SPI in the documents: "Annex IV - Security Manual", "Technical and business specifications of the Brazilian instant payment ecosystem" and "Annex III - Communication Interfaces Manual" defined in the SPI.
The negotiated tunnel is TLS version 1.2 with mutual authentication, using the HTTP protocol version 1.1 with a minimum Cipher Suite of ECDHE-RSA-AES-128-GCM-SHA256.

This API will automatically decompress a response that comes compressed in the gzip standard. If you choose to compress the sending data, the API caller must do so in gzip format.

This request uses the following headers by default.
"Accept-Encoding: gzip"
"User-Agent: DNLC/0.0.0.0", where 0.0.0.0 is the version of the HSM client library used.

Certificate validation with the host name is done by checking that the Common Name field or Subject Alternate Name field of the certificate matches the host name of the URL passed as a parameter.

When making an HTTP request, 2 operations are performed, one to use the HSM objects (private key, certificate and chain, used for tunnel authentication) and the other to open the HTTP session with the HTTP server.
To optimize resources, the session with the HTTP server is kept open and cached; likewise, the session with the HSM is cached by default (the HSM session can optionally be set not to be cached).
The HTTP session is associated with the session opened with the HSM, which means that to reuse an HTTP session you must use the same HSM session that was previously used to open the HTTP session.
The HTTP session is physically closed when the session with the HSM is physically closed.
The HSM session and the HTTP session have thread-session affinity and cannot be used simultaneously by several threads.

Long Polling is adjusted by setting the HTTP operation timeout (POST/GET/DELETE) according to the HTTP server settings.

See also

DFree() DPIXPost() DPIXGet() DPIXDelete()

Examples

post_put_get_delete_pix.c.

DPIXDelete()

int AAP_API DPIXDelete	(	HSESSIONCTX	hSession,
		const char *	szKeyId,
		const char *	szCertId,
		const char *	szPIXCertChainId,
		const char *	szURL,
		DWORD	dwCountRequestHeaderList,
		const char *	pszRequestHeaderList[],
		DWORD	dwTimeOut,
		DWORD *	pdwSizeResponseHeaders,
		BYTE **	ppbResponseHeaders,
		DWORD *	pdwSizeResponseBody,
		BYTE **	ppbResponseBody,
		DWORD	dwParam )

#include <dinamo.h>

It makes a secure HTTP DELETE request following the PIX standard defined in SPI (Instant Payment System).

Note

Configure timeout settings. Refer to the Best Practices section for more details.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szKeyId	Name of the private key used for tunnel establishment. Corresponds to a CPIC certificate.
[in]	szCertId	Name of the certificate used for tunnel establishment. This is the PSP Digital Certificate registered with SPI for connection, also known as CPIC or CERTPIC.
[in]	szPIXCertChainId	Name of the PKCS#7 string used to check the PIX server (ICOM or DICT). As of version 5.0.23 of the HSM firmware, it is possible to use a PKCS#7 object containing several strings.
[in]	szURL	URL of the server PIX (ICOM or DICT).
[in]	dwCountRequestHeaderList	Number of lines filled in pszRequestHeaderList.
[in]	pszRequestHeaderList	Lines containing the customized HTTP headers that will be used in the request. Can be passed null if you want to use the default header without changes. This option will overwrite the default headers if they overlap. To remove a header, pass the name of the header without a value (e.g. Accept:). To include a header with no content, use ; instead of : (e.g. Accept;). Do NOT use CRLF terminators in headers. Passing these terminators may cause unwanted behavior. Formatting will be done internally. This option cannot be used to change the first line of the request (e.g. POST, PUT, GET, DELETE), which is not a header. The corresponding API, described in this manual, must be used. The default initial header includes Host, User-Agent, Accept, Accept-Encoding.
[in]	dwTimeOut	Operation timeout in milliseconds. Can be set to 0 for no timeout.
[out]	pdwSizeResponseHeaders	Pointer that will contain the size of the data stored in the ppbResponseHeaders buffer, in bytes.
[out]	ppbResponseHeaders	Internally allocated buffer that will contain the header returned by the request. The size allocated is defined in pdwSizeResponseHeaders. This pointer must be freed using the DFree() API.
[out]	pdwSizeResponseBody	Pointer that will contain the size of the data stored in the ppbResponseBody buffer, in bytes.
[out]	ppbResponseBody	Internally allocated buffer that will contain the body returned by the request. The allocated size is defined in pdwSizeResponseBody. This pointer must be freed using the DFree() API.
[in]	dwParam	Value Meaning 0 Standard option for SPB certificates. Does not verify the certificate against the hostname. PIX_VERIFY_HOST_NAME Verifies the certificate against the hostname. PIX_BASIC_HTTP_HEADER Uses the basic initial HTTP header. Includes Host and User-Agent. PIX_GZIP Includes the Accept-Encoding: gzip header if the basic header is enabled.

Returns

0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.

Notes

It executes a secure request following the PIX standard defined in the SPI in the documents: "Annex IV - Security Manual", "Technical and business specifications of the Brazilian instant payment ecosystem" and "Annex III - Communication Interfaces Manual" defined in the SPI.
The negotiated tunnel is TLS version 1.2 with mutual authentication, using the HTTP protocol version 1.1 with a minimum Cipher Suite of ECDHE-RSA-AES-128-GCM-SHA256.

This API will automatically decompress a response that comes compressed in the gzip standard. If you choose to compress the sending data, the API caller must do so in gzip format.

This request uses the following headers by default.
"Accept-Encoding: gzip"
"User-Agent: DNLC/0.0.0.0", where 0.0.0.0 is the version of the HSM client library used.

Certificate validation with the host name is done by checking that the Common Name field or Subject Alternate Name field of the certificate matches the host name of the URL passed as a parameter.

When making an HTTP request, 2 operations are performed, one to use the HSM objects (private key, certificate and chain, used for tunnel authentication) and the other to open the HTTP session with the HTTP server.
To optimize resources, the session with the HTTP server is kept open and cached; likewise, the session with the HSM is cached by default (the HSM session can optionally be set not to be cached).
The HTTP session is associated with the session opened with the HSM, which means that to reuse an HTTP session you must use the same HSM session that was previously used to open the HTTP session.
The HTTP session is physically closed when the session with the HSM is physically closed.
The HSM session and the HTTP session have thread-session affinity and cannot be used simultaneously by several threads.

Long Polling is adjusted by setting the HTTP operation timeout (POST/GET/DELETE) according to the HTTP server settings.

See also

DFree() DPIXPost() DPIXPut() DPIXGet()

Examples

post_put_get_delete_pix.c.

DPIXOpenHandle()

int AAP_API DPIXOpenHandle	(	HPIXSESSIONCTX *	phPIXSession,
		const char *	szKeyId,
		const char *	szCertId,
		const char *	szPIXCertChainId,
		DWORD	dwParam,
		BYTE *	pbData,
		DWORD	dwDataLen,
		DWORD	dwFlags,
		DWORD	dwPixFlags )

#include <dinamo.h>

Creates a ` PIX` handle, which encapsulates a persistent HTTP connection and the TLS material (certificate, chain, and key) used in the mTLS tunnel.

The handle is independent of any session with the HSM. A session is obtained internally, via DOpenSession(), only during the TLS handshake, and is returned immediately afterward. Requests that reuse the connection do not access the HSM.

The parameters dwParam, pbData, dwDataLen, and dwFlags are exactly the same as those that would be passed to DOpenSession(), and they are stored in the handle. They are cleared from memory when the handle is destroyed using DPIXCloseHandle().

Parameters

[out]	phPIXSession	A pointer that will hold the created handle.
[in]	szKeyId	Identifier of the private key used in the mTLS tunnel.
[in]	szCertId	Client certificate identifier.
[in]	szPIXCertChainId	Peer certificate chain identifier (PKCS#7).
[in]	dwParam	Authentication type, as specified by DOpenSession().
[in]	pbData	Authentication data, as specified by DOpenSession().
[in]	dwDataLen	Size of pbData, in bytes.
[in]	dwFlags	Session opening flags, as specified by DOpenSession().
[in]	dwPixFlags	Value Meaning 0 Standard. The handle is a lightweight reference that does not maintain a connection between calls: each request retrieves a connection from the HTTP session cache and returns it when finished. DN_PIX_NOT_IN_CACHE The handle is unique to the caller and maintains the HTTP connection until DPIXCloseHandle() is called.

Both modes follow the same HSESSIONCTX contract: a handle can be used by multiple threads, but never simultaneously. To make requests in parallel, open one handle per thread—in the default mode, this does not imply one connection per handle, since all threads share the same HTTP connection cache.

Returns

0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.

See also

DPIXCloseHandle() DOpenSession()

Examples

pix_handle_no_cache.c, pix_handle_request.c, and pix_handle_stats.c.

DPIXCloseHandle()

int AAP_API DPIXCloseHandle	(	HPIXSESSIONCTX *	phPIXSession,
		DWORD	dwReserved )

#include <dinamo.h>

Destroys a handle PIX created by DPIXOpenHandle(), clearing the credentials stored in it from memory.

The effect on connections depends on how the handle was created. A DN_PIX_NO_CACHE handle is unique, so its HTTP connection is closed here. A cached handle does not have its own connection: only the reference is released, and the cache connections remain available to other callers until the idle scan closes them. To close them immediately, use DPIXSetCacheParam() with PIXCP_CLEAR.

Parameters

[in,out]	phPIXSession	Pointer to the handle. Returns NULL.
[in]	dwReserved	Reserved for future use (must be 0).

Returns

0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.

See also

DPIXOpenHandle()

Examples

pix_handle_no_cache.c, pix_handle_request.c, and pix_handle_stats.c.

DPIXGetHandleParam()

int AAP_API DPIXGetHandleParam	(	HPIXSESSIONCTX	hPIXSession,
		DWORD	dwParam,
		BYTE *	pbData,
		DWORD *	pdwDataLen,
		DWORD	dwReserved )

#include <dinamo.h>

Retrieves information and counters from a ` PIX` handle.

The values always correspond to the specified handle, in both modes. A cached handle borrows a connection for each request but records the result in itself at the end of each one: the counters reflect the requests made by this handle, not the connection that served it.

Parameters

[in]	hPIXSession	Handle PIX.
[in]	dwParam	Value Meaning PIXP_HTTP_RET pbData type : ND_uint64_t HTTP response code for the last request. PIXP_HTTP_REQ_DETAILS pbData type : PIX_HTTP_REQUEST_DETAILS Details of the last request. PIXP_STATS pbData type : PIX_HANDLE_STATS Accumulated counters for the handle. The dwVersion field must be set to PIX_HANDLE_STATS_VERSION before the call.
[out]	pbData	Buffer that will receive the value. Pass NULL to determine the required size: the function writes the size to pdwDataLen and returns zero, following the DGetSessionParam() convention.
[in,out]	pdwDataLen	Size of pbData on input; required size or size written to output. If the buffer is smaller than required, the function returns D_MORE_DATA and writes the required size here.
[in]	dwReserved	Reserved for future use (must be 0).

Returns

0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.

See also

DPIXOpenHandle()

Examples

pix_handle_stats.c.

DPIXSetCacheParam()

int AAP_API DPIXSetCacheParam	(	DWORD	dwParam,
		BYTE *	pbData,
		DWORD	dwDataLen,
		DWORD	dwReserved )

#include <dinamo.h>

Configures the HTTP session cache for PIX, which is used by the DPIXPost(), DPIXPut(), DPIXGet(), and DPIXDelete() functions.

The cache is library-scoped. Handles created explicitly without caching using DPIXOpenHandle() belong to the creator; they are not cached and are not affected by this function.

Parameters

[in]	dwParam	Value Meaning PIXCP_CLEAR pbData type : NULL Flags HTTP sessions in the cache to be closed. Idle sessions are closed immediately. Sessions that are in use are closed at the end of the current request, rather than being returned to the cache. PIXCP_MAX_HANDLES pbData type : DWORD Maximum number of HTTP sessions cached. Zero means no limit. Reducing this value does not close existing sessions; it only prevents new ones from being created. Equivalent to the HSM_PIX_POOL_MAX_HANDLES environment variable. PIXCP_IDLE_TTL pbData Type : DWORD The time, in seconds, after which an idle HTTP session is closed. Zero disables this behavior. Equivalent to the HSM_PIX_POOL_IDLE_TTL environment variable.
[in]	pbData	Value to be defined, based on dwParam.
[in]	dwDataLen	Size of pbData, in bytes.
[in]	dwReserved	Reserved for future use (must be 0).

Returns

0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.

See also

DPIXGetCacheParam() DPIXOpenHandle()

Examples

pix_handle_stats.c.

DPIXGetCacheParam()

int AAP_API DPIXGetCacheParam	(	DWORD	dwParam,
		BYTE *	pbData,
		DWORD *	pdwDataLen,
		DWORD	dwReserved )

#include <dinamo.h>

Restores the configuration and counters for the HTTP session cache in PIX.

Parameters

[in]	dwParam	Value Meaning PIXCP_MAX_HANDLES pbData type : DWORD Maximum number of cached HTTP sessions. PIXCP_IDLE_TTL pbData type : DWORD Idle time, in seconds, before an HTTP session is closed. PIXCP_STATS pbData type : PIX_POOL_STATS Cache counters. The dwVersion field must be set to PIX_POOL_STATS_VERSION before the call.
[out]	pbData	Buffer that will receive the value. Pass NULL to determine the required size: the function writes the size to pdwDataLen and returns zero, following the DGetSessionParam() convention.
[in,out]	pdwDataLen	Size of pbData on input; required size or size written to output. If the buffer is smaller than required, the function returns D_MORE_DATA and writes the required size here.
[in]	dwReserved	Reserved for future use (must be 0).

Returns

0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.

See also

DPIXSetCacheParam()

Examples

pix_handle_stats.c.

DPIXRequest()

int AAP_API DPIXRequest	(	HPIXSESSIONCTX	hPIXSession,
		const PIX_REQUEST *	pstRequest,
		PIX_RESPONSE *	pstResponse,
		DWORD	dwReserved )

#include <dinamo.h>

Makes an HTTP request using the handle ` PIX`, for any method.

The method is specified in #PIX_REQUEST::method, and the input parameters and return value are stored in structures, so that adding a field in the future does not change this function's signature.

The HTTP connection and TLS settings come from hPIXSession, not from a session with the HSM: the key, certificate, and certificate chain were set in DPIXOpenHandle().

The pstResponse buffers are allocated internally. Free them using DPIXFreeResponse(), even if the function returns an error—a partial response may have been received before the failure occurred.

pstResponse is reset to zero right at the beginning of the call. The only exception is an invalid dwVersion: in that case, the structure is not modified because its layout is unknown.

Parameters

[in]	hPIXSession	Handle PIX created by DPIXOpenHandle().
[in]	pstRequest	Request data. The dwVersion field must be set to PIX_REQUEST_VERSION before the call.
[out]	pstResponse	Response received. The dwVersion field must be set to PIX_RESPONSE_VERSION before the call. It can be set to NULL to discard the response.
[in]	dwReserved	Reserved for future use (must be 0).

Returns

0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.

See also

DPIXOpenHandle() DPIXFreeResponse() DPIXPost()

Examples

pix_handle_no_cache.c, pix_handle_request.c, and pix_handle_stats.c.

DPIXFreeResponse()

int AAP_API DPIXFreeResponse

(

PIX_RESPONSE *

pstResponse

)

#include <dinamo.h>

Frees the buffers of a PIX_RESPONSE filled by DPIXRequest().

Clears all fields except dwVersion (to preserve the layout). Since the pointers are reset to zero, calling it twice is safe. Passing NULL does nothing.

Parameters

[in,out]

pstResponse

Response pending approval.

Returns

0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.

See also

DPIXRequest()

Examples

pix_handle_no_cache.c, pix_handle_request.c, and pix_handle_stats.c.