Utils Class

Properties   Methods   Events   Config Settings   Errors  

The Utils class offers a selection of popular helper methods that may be of use in a variety of scenarios.

Class Name

SecureBlackbox_Utils

Procedural Interface

 secureblackbox_utils_open();
 secureblackbox_utils_close($res);
 secureblackbox_utils_register_callback($res, $id, $function);
 secureblackbox_utils_get_last_error($res);
 secureblackbox_utils_get_last_error_code($res);
 secureblackbox_utils_set($res, $id, $index, $value);
 secureblackbox_utils_get($res, $id, $index);
 secureblackbox_utils_do_addpartfrombytes($res, $data);
 secureblackbox_utils_do_addpartfromfile($res, $filename);
 secureblackbox_utils_do_base64decode($res, $value, $useurlencoding);
 secureblackbox_utils_do_base64encode($res, $bytes, $useurlencoding);
 secureblackbox_utils_do_base64encodelines($res, $bytes, $linelen);
 secureblackbox_utils_do_config($res, $configurationstring);
 secureblackbox_utils_do_datetostring($res, $value);
 secureblackbox_utils_do_doaction($res, $actionid, $actionparams);
 secureblackbox_utils_do_geterrordescription($res, $errorcode);
 secureblackbox_utils_do_getlocaldnsname($res);
 secureblackbox_utils_do_getlocalip($res, $ipv6);
 secureblackbox_utils_do_getlocalips($res, $ipv4, $ipv6);
 secureblackbox_utils_do_getparttobytes($res, $index);
 secureblackbox_utils_do_getparttofile($res, $index, $filename);
 secureblackbox_utils_do_getremoteip($res, $hostname, $ipv6, $dnsmode, $dnsservers, $timeout);
 secureblackbox_utils_do_getremoteips($res, $hostname, $ipv4, $ipv6, $dnsmode, $dnsservers, $timeout);
 secureblackbox_utils_do_getvaluebyname($res, $name);
 secureblackbox_utils_do_hexdecode($res, $value);
 secureblackbox_utils_do_hexencode($res, $bytes);
 secureblackbox_utils_do_indexofname($res, $name);
 secureblackbox_utils_do_loadmultipartfrombytes($res, $contenttype, $data);
 secureblackbox_utils_do_loadmultipartfromfile($res, $contenttype, $filename);
 secureblackbox_utils_do_loadnamevaluepairs($res, $data, $format, $namevalueseparator, $pairseparator, $trimvalues);
 secureblackbox_utils_do_oidtostring($res, $bytes);
 secureblackbox_utils_do_removenamevaluepair($res, $name);
 secureblackbox_utils_do_reset($res);
 secureblackbox_utils_do_savemultipartcontenttype($res);
 secureblackbox_utils_do_savemultiparttobytes($res, $multipartmode);
 secureblackbox_utils_do_savemultiparttofile($res, $multipartmode, $filename);
 secureblackbox_utils_do_savenamevaluepairs($res, $format, $namevalueseparator, $pairseparator);
 secureblackbox_utils_do_setvaluebyname($res, $name, $value);
 secureblackbox_utils_do_stringdecode($res, $bytes, $encoding);
 secureblackbox_utils_do_stringencode($res, $value, $encoding);
 secureblackbox_utils_do_stringtodate($res, $value);
 secureblackbox_utils_do_stringtooid($res, $value);
 secureblackbox_utils_do_urldecode($res, $value);
 secureblackbox_utils_do_urlencode($res, $value);

Remarks

If you need to resolve a hostname to an IP address, encode a string using a specific character encoding, or compose a multipart message, look no further. This is exactly what Utils is intended for. Below is a summary of little useful features that this class can help you with.

Encoding and decoding

• Encode binary data to base64 and decode it back (Base64Encode and Base64Decode)
• Hex-encode and decode (HexEncode and HexDecode)
• Encode and decode dates - particularly handy when working with other suite components that expect string dates (StringToDate, DateToString)
• Convert object identifiers from and to string representation (StringToOid, OidToString)
• Convert string to any supported character encoding (StringEncode and StringDecode).

Networking helpers

• Get local network parameters with GetLocalIP and GetLocalDNSName
• Resolve remote domain names into IP addresses (GetRemoteIP)
• URL-encode and decode HTTP and other data (UrlEncode and UrlDecode).

Work with multipart MIME messages

• Compose a multipart body with AddPartFromBytes and SaveMultipartToBytes
• Load and process existing multiparts with LoadMultipartFromBytes and GetPartToBytes.

Utils class also offers a useful GetErrorDescription method that lets you obtain a human-readable message for every SecureBlackbox error code you might get. // base64Encode byte[] bytes = ("Life is like riding a bicycle. To keep your balance," + " you must keep moving. (Albert Einstein)").getBytes(); String base64Encoded = utils.base64Encode(bytes,false); System.out.println(base64Encoded); // base64Decode String decoded = new String(utils.base64Decode(base64Encoded,false)); System.out.println(decoded); // Example: Using another SecureBlackbox component to get a string // and convert it to a Java Date object MessageVerifier verifier = new MessageVerifier(); verifier.setInputFile("signedMessage.bin"); verifier.setOutputFile("output.txt"); verifier.verify(); String verifiedDate = verifier.getValidatedSigningTime(); // Retrieving the string: 2024-05-17 13:25:26 Date date = utils.stringToDate(verifiedDate); // Using utils to convert it System.out.println(date); // Output : Fri May 17 13:25:26 CEST 2024 // Retrieving remote IP String hostName = "nsoftware.com"; System.out.println("Hostname: " + hostName + " has this IP: " + utils.getRemoteIP("www.nsoftware.com",false,dmAuto,"",60)); // Output: Hostname: nsoftware.com has this IP: 52.168.9.41 // Hex Encode byte[] bytes = ("Genius is one percent inspiration and " + "ninety-nine percent perspiration.(Thomas Edison)").getBytes(); String hexEncoded = utils.hexEncode(bytes); System.out.println(hexEncoded); // Hex Decode String decoded = new String(utils.hexDecode(hexEncoded)); System.out.println(decoded);

Property List

---

The following is the full list of the properties of the class with short descriptions. Click on the links for further details.

Method List

---

The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

Event List

---

The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.

Config Settings

---

The following is a list of config settings for the class with short descriptions. Click on the links for further details.

MultipartPartCount Property (SecureBlackbox_Utils Class)

The number of records in the MultipartPart arrays.

Object Oriented Interface

public function getMultipartPartCount();
public function setMultipartPartCount($value);

Procedural Interface

secureblackbox_utils_get($res, 1 );
secureblackbox_utils_set($res, 1, $value );

Default Value

0

Remarks

This property controls the size of the following arrays:

• MultipartPartContentDescription
• MultipartPartContentDisposition
• MultipartPartContentID
• MultipartPartContentTransferEncoding
• MultipartPartContentType
• MultipartPartCustomHeaders
• MultipartPartFieldName
• MultipartPartFieldValue
• MultipartPartFileName
• MultipartPartHandle

The array indices start at 0 and end at MultipartPartCount - 1.

This property is not available at design time.

Data Type

Integer

MultipartPartContentDescription Property (SecureBlackbox_Utils Class)

Provides a description for the part ( Content-Description header property).

Object Oriented Interface

public function getMultipartPartContentDescription($multipartpartindex);
public function setMultipartPartContentDescription($multipartpartindex, $value);

Procedural Interface

secureblackbox_utils_get($res, 2 , $multipartpartindex);
secureblackbox_utils_set($res, 2, $value , $multipartpartindex);

Default Value

''

Remarks

Provides a description for the part (Content-Description header field)

The $multipartpartindex parameter specifies the index of the item in the array. The size of the array is controlled by the MultipartPartCount property.

This property is not available at design time.

Data Type

String

MultipartPartContentDisposition Property (SecureBlackbox_Utils Class)

Specifies the disposition of the part ( Content-Disposition header property).

Object Oriented Interface

public function getMultipartPartContentDisposition($multipartpartindex);
public function setMultipartPartContentDisposition($multipartpartindex, $value);

Procedural Interface

secureblackbox_utils_get($res, 3 , $multipartpartindex);
secureblackbox_utils_set($res, 3, $value , $multipartpartindex);

Default Value

''

Remarks

Specifies the disposition of the part (Content-Disposition header field)

The $multipartpartindex parameter specifies the index of the item in the array. The size of the array is controlled by the MultipartPartCount property.

This property is not available at design time.

Data Type

String

MultipartPartContentID Property (SecureBlackbox_Utils Class)

Specifies the ID of the part ( Content-ID header property).

Object Oriented Interface

public function getMultipartPartContentID($multipartpartindex);
public function setMultipartPartContentID($multipartpartindex, $value);

Procedural Interface

secureblackbox_utils_get($res, 4 , $multipartpartindex);
secureblackbox_utils_set($res, 4, $value , $multipartpartindex);

Default Value

''

Remarks

Specifies the ID of the part (Content-ID header field)

The $multipartpartindex parameter specifies the index of the item in the array. The size of the array is controlled by the MultipartPartCount property.

This property is not available at design time.

Data Type

String

MultipartPartContentTransferEncoding Property (SecureBlackbox_Utils Class)

Specifies the transfer encoding for the part ( Content-Transfer-Encoding header property).

Object Oriented Interface

public function getMultipartPartContentTransferEncoding($multipartpartindex);
public function setMultipartPartContentTransferEncoding($multipartpartindex, $value);

Procedural Interface

secureblackbox_utils_get($res, 5 , $multipartpartindex);
secureblackbox_utils_set($res, 5, $value , $multipartpartindex);

Default Value

''

Remarks

Specifies the transfer encoding for the part (Content-Transfer-Encoding header field)

The $multipartpartindex parameter specifies the index of the item in the array. The size of the array is controlled by the MultipartPartCount property.

This property is not available at design time.

Data Type

String

MultipartPartContentType Property (SecureBlackbox_Utils Class)

Specifies the content type of the part ( Content-Type header property).

Object Oriented Interface

public function getMultipartPartContentType($multipartpartindex);
public function setMultipartPartContentType($multipartpartindex, $value);

Procedural Interface

secureblackbox_utils_get($res, 6 , $multipartpartindex);
secureblackbox_utils_set($res, 6, $value , $multipartpartindex);

Default Value

''

Remarks

Specifies the content type of the part (Content-Type header field)

The $multipartpartindex parameter specifies the index of the item in the array. The size of the array is controlled by the MultipartPartCount property.

This property is not available at design time.

Data Type

String

MultipartPartCustomHeaders Property (SecureBlackbox_Utils Class)

Assign any custom HTTP headers to be added to the part header.

Object Oriented Interface

public function getMultipartPartCustomHeaders($multipartpartindex);
public function setMultipartPartCustomHeaders($multipartpartindex, $value);

Procedural Interface

secureblackbox_utils_get($res, 7 , $multipartpartindex);
secureblackbox_utils_set($res, 7, $value , $multipartpartindex);

Default Value

''

Remarks

Assign any custom HTTP headers to be added to the part header.

The $multipartpartindex parameter specifies the index of the item in the array. The size of the array is controlled by the MultipartPartCount property.

This property is not available at design time.

Data Type

String

MultipartPartFieldName Property (SecureBlackbox_Utils Class)

Specifies the property name of the form part ( name parameter in Content-Disposition header property).

Object Oriented Interface

public function getMultipartPartFieldName($multipartpartindex);
public function setMultipartPartFieldName($multipartpartindex, $value);

Procedural Interface

secureblackbox_utils_get($res, 8 , $multipartpartindex);
secureblackbox_utils_set($res, 8, $value , $multipartpartindex);

Default Value

''

Remarks

Specifies the field name of the form part (name parameter in Content-Disposition header field).

The $multipartpartindex parameter specifies the index of the item in the array. The size of the array is controlled by the MultipartPartCount property.

This property is not available at design time.

Data Type

String

MultipartPartFieldValue Property (SecureBlackbox_Utils Class)

Specifies the property value of the form part (the part's content).

Object Oriented Interface

public function getMultipartPartFieldValue($multipartpartindex);
public function setMultipartPartFieldValue($multipartpartindex, $value);

Procedural Interface

secureblackbox_utils_get($res, 9 , $multipartpartindex);
secureblackbox_utils_set($res, 9, $value , $multipartpartindex);

Default Value

''

Remarks

Specifies the field value of the form part (the part's content).

The $multipartpartindex parameter specifies the index of the item in the array. The size of the array is controlled by the MultipartPartCount property.

This property is not available at design time.

Data Type

String

MultipartPartFileName Property (SecureBlackbox_Utils Class)

Specifies the filename for the form part ( filename parameter in Content-Disposition header property).

Object Oriented Interface

public function getMultipartPartFileName($multipartpartindex);
public function setMultipartPartFileName($multipartpartindex, $value);

Procedural Interface

secureblackbox_utils_get($res, 10 , $multipartpartindex);
secureblackbox_utils_set($res, 10, $value , $multipartpartindex);

Default Value

''

Remarks

Specifies the filename for the form part (filename parameter in Content-Disposition header field).

The $multipartpartindex parameter specifies the index of the item in the array. The size of the array is controlled by the MultipartPartCount property.

This property is not available at design time.

Data Type

String

MultipartPartHandle Property (SecureBlackbox_Utils Class)

Allows to get or set a 'handle', a unique identifier of the underlying property object.

Object Oriented Interface

public function getMultipartPartHandle($multipartpartindex);
public function setMultipartPartHandle($multipartpartindex, $value);

Procedural Interface

secureblackbox_utils_get($res, 11 , $multipartpartindex);
secureblackbox_utils_set($res, 11, $value , $multipartpartindex);

Default Value

0

Remarks

Allows to get or set a 'handle', a unique identifier of the underlying property object. Use this property to assign objects of the same type in a quicker manner, without copying them fieldwise.

When you pass a handle of one object to another, the source object is copied to the destination rather than assigned. It is safe to get rid of the original object after such operation. pdfSigner.setSigningCertHandle(certMgr.getCertHandle());

The $multipartpartindex parameter specifies the index of the item in the array. The size of the array is controlled by the MultipartPartCount property.

This property is not available at design time.

Data Type

Long64

NameValuePairCount Property (SecureBlackbox_Utils Class)

The number of records in the NameValuePair arrays.

Object Oriented Interface

public function getNameValuePairCount();
public function setNameValuePairCount($value);

Procedural Interface

secureblackbox_utils_get($res, 12 );
secureblackbox_utils_set($res, 12, $value );

Default Value

0

Remarks

This property controls the size of the following arrays:

• NameValuePairCategory
• NameValuePairFormat
• NameValuePairName
• NameValuePairValue

The array indices start at 0 and end at NameValuePairCount - 1.

This property is not available at design time.

Data Type

Integer

NameValuePairCategory Property (SecureBlackbox_Utils Class)

Specifies the string category of the contained value.

Object Oriented Interface

public function getNameValuePairCategory($namevaluepairindex);
public function setNameValuePairCategory($namevaluepairindex, $value);

Procedural Interface

secureblackbox_utils_get($res, 13 , $namevaluepairindex);
secureblackbox_utils_set($res, 13, $value , $namevaluepairindex);

Default Value

''

Remarks

Specifies the string category of the contained value.

This property allows to check or set the category (or type) associated with the contained value. Depending on the format used to load or save the string, the category parameter may or may not be used.

For example, for ASN.1 property lists the category contains the ASN.1 tag of the contained data (OCTETSTRING, UTF8STRING, INTEGER, ...). For basic (name, value) pairs, such as HTTP headers, the category parameter is not used.

The $namevaluepairindex parameter specifies the index of the item in the array. The size of the array is controlled by the NameValuePairCount property.

This property is not available at design time.

Data Type

String

NameValuePairFormat Property (SecureBlackbox_Utils Class)

Specifies the format (encoding) of the value contained in the Value property.

Object Oriented Interface

public function getNameValuePairFormat($namevaluepairindex);
public function setNameValuePairFormat($namevaluepairindex, $value);

Procedural Interface

secureblackbox_utils_get($res, 14 , $namevaluepairindex);
secureblackbox_utils_set($res, 14, $value , $namevaluepairindex);

Default Value

0

Remarks

Specifies the format (encoding) of the value contained in the NameValuePairValue property.

Use this property to check or set the format of the contained value. Remember to provide the actual value in the appropriate format that matches this setting: utils.NameValuePairs[0].Name = "key"; utils.NameValuePairs[0].Format = svfBinary; utils.NameValuePairs[0].Name = "0a1b2c3d4e5f6071";

The following formats are currently supported:

The $namevaluepairindex parameter specifies the index of the item in the array. The size of the array is controlled by the NameValuePairCount property.

This property is not available at design time.

Data Type

Integer

NameValuePairName Property (SecureBlackbox_Utils Class)

The name element in a (name, value) pair.

Object Oriented Interface

public function getNameValuePairName($namevaluepairindex);
public function setNameValuePairName($namevaluepairindex, $value);

Procedural Interface

secureblackbox_utils_get($res, 15 , $namevaluepairindex);
secureblackbox_utils_set($res, 15, $value , $namevaluepairindex);

Default Value

''

Remarks

The name element in a (name, value) pair.

The $namevaluepairindex parameter specifies the index of the item in the array. The size of the array is controlled by the NameValuePairCount property.

This property is not available at design time.

Data Type

String

NameValuePairValue Property (SecureBlackbox_Utils Class)

The value element in a (name, value) pair.

Object Oriented Interface

public function getNameValuePairValue($namevaluepairindex);
public function setNameValuePairValue($namevaluepairindex, $value);

Procedural Interface

secureblackbox_utils_get($res, 16 , $namevaluepairindex);
secureblackbox_utils_set($res, 16, $value , $namevaluepairindex);

Default Value

''

Remarks

The value element in a (name, value) pair.

The $namevaluepairindex parameter specifies the index of the item in the array. The size of the array is controlled by the NameValuePairCount property.

This property is not available at design time.

Data Type

String

AddPartFromBytes Method (SecureBlackbox_Utils Class)

Adds a new part to MultipartMessage from the specified byte array.

Object Oriented Interface

public function doAddPartFromBytes($data);

Procedural Interface

secureblackbox_utils_do_addpartfrombytes($res, $data);

Remarks

The method adds a new part to MultipartMessage list with the specified data as the part's content.

Returns the index of the added part.

AddPartFromFile Method (SecureBlackbox_Utils Class)

Adds a new part to MultipartMessage from the specified file.

Object Oriented Interface

public function doAddPartFromFile($filename);

Procedural Interface

secureblackbox_utils_do_addpartfromfile($res, $filename);

Remarks

The method adds a new part to MultipartMessage list with the specified file data as the part's content.

Returns the index of the added part.

Base64Decode Method (SecureBlackbox_Utils Class)

Decodes a base64 string to a byte array.

Object Oriented Interface

public function doBase64Decode($value, $useurlencoding);

Procedural Interface

secureblackbox_utils_do_base64decode($res, $value, $useurlencoding);

Remarks

Use this method to decode a base64-encoded string to a byte array. The UseURLEncoding parameter specifies whether the URL-Base64 modification should be used when decoding the string. byte[] arr = utils.Base64Decode("SGVsbG8sIHdvcmxkIQ==", false);

Base64Encode Method (SecureBlackbox_Utils Class)

Encodes a byte array in base64.

Object Oriented Interface

public function doBase64Encode($bytes, $useurlencoding);

Procedural Interface

secureblackbox_utils_do_base64encode($res, $bytes, $useurlencoding);

Remarks

Use this method to encode binary data contained in Bytes to a base64 string. The UseURLEncoding parameter specifies whether additional URL encoding should be applied to the resulting string (with + and / characters replaced with - and _, respectively). string encoded = utils.Base64Encode(buf, false);

Base64EncodeLines Method (SecureBlackbox_Utils Class)

Encodes the Bytes array containing binary data to a multi-line Base64.

Object Oriented Interface

public function doBase64EncodeLines($bytes, $linelen);

Procedural Interface

secureblackbox_utils_do_base64encodelines($res, $bytes, $linelen);

Remarks

Use this method to encode large amounts of binary data to multi-line base64 strings. Use LineLen parameter to provide the maximal length of each base64 line.

Config Method (SecureBlackbox_Utils Class)

Sets or retrieves a configuration setting.

Object Oriented Interface

public function doConfig($configurationstring);

Procedural Interface

secureblackbox_utils_do_config($res, $configurationstring);

Remarks

Config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

DateToString Method (SecureBlackbox_Utils Class)

Converts a variable of Date type to the respective string representation.

Object Oriented Interface

public function doDateToString($value);

Procedural Interface

secureblackbox_utils_do_datetostring($res, $value);

Remarks

Use this method to convert a value of a platform date type to a string representation accepted by various SecureBlackbox methods and properties.

DoAction Method (SecureBlackbox_Utils Class)

Performs an additional action.

Object Oriented Interface

public function doDoAction($actionid, $actionparams);

Procedural Interface

secureblackbox_utils_do_doaction($res, $actionid, $actionparams);

Remarks

DoAction is a generic method available in every class. It is used to perform an additional action introduced after the product major release. The list of actions is not fixed, and may be flexibly extended over time.

The unique identifier (case insensitive) of the action is provided in the ActionID parameter.

ActionParams contains the value of a single parameter, or a list of multiple parameters for the action in the form of PARAM1=VALUE1;PARAM2=VALUE2;....

Common ActionIDs:

GetErrorDescription Method (SecureBlackbox_Utils Class)

Returns an error description by an error code.

Object Oriented Interface

public function doGetErrorDescription($errorcode);

Procedural Interface

secureblackbox_utils_do_geterrordescription($res, $errorcode);

Remarks

Use this method to get a human readable description of an error by its code. Returns an empty string if the error code is not recognized.

GetLocalDNSName Method (SecureBlackbox_Utils Class)

Returns the DNS name of the local system.

Object Oriented Interface

public function doGetLocalDNSName();

Procedural Interface

secureblackbox_utils_do_getlocaldnsname($res);

Remarks

Use this property to get the registered DNS or network name of the local system.

GetLocalIP Method (SecureBlackbox_Utils Class)

Returns the primary IP address of the local system.

Object Oriented Interface

public function doGetLocalIP($ipv6);

Procedural Interface

secureblackbox_utils_do_getlocalip($res, $ipv6);

Remarks

Use this method to obtain the default IP address of the local system.

GetLocalIPs Method (SecureBlackbox_Utils Class)

Returns a list of local IP addresses.

Object Oriented Interface

public function doGetLocalIPs($ipv4, $ipv6);

Procedural Interface

secureblackbox_utils_do_getlocalips($res, $ipv4, $ipv6);

Remarks

Use this method to request a list of all local IP addresses available in the system. Set IPv4 and IPv6 as required to filter IPv4 and IPv6 interfaces in or out respectively.

GetPartToBytes Method (SecureBlackbox_Utils Class)

Saves the data from the specified part to a byte array.

Object Oriented Interface

public function doGetPartToBytes($index);

Procedural Interface

secureblackbox_utils_do_getparttobytes($res, $index);

Remarks

Use this method to store the data of the specified part to a byte array.

Index must be greater than or equal to 0, and less than the part count.

GetPartToFile Method (SecureBlackbox_Utils Class)

Saves the data from the specified part to a file.

Object Oriented Interface

public function doGetPartToFile($index, $filename);

Procedural Interface

secureblackbox_utils_do_getparttofile($res, $index, $filename);

Remarks

Use this method to store the data of the specified part to a file.

Index must be greater than or equal to 0, and less than the part count.

GetRemoteIP Method (SecureBlackbox_Utils Class)

Gets the IP address of a remote host.

Object Oriented Interface

public function doGetRemoteIP($hostname, $ipv6, $dnsmode, $dnsservers, $timeout);

Procedural Interface

secureblackbox_utils_do_getremoteip($res, $hostname, $ipv6, $dnsmode, $dnsservers, $timeout);

Remarks

Use this property to resolve the address of a remote host using the provided DNS settings. Set IPv6 to true to force resolution of both IPv4 and IPv6 addresses.

Use the Timeout setting to specify maximal resolution time, and the DNSServer parameter to list the addresses of DNS servers to use for address resolution. Separate individual servers in the list with commas or semicolons. If an empty server list is provided, the component will use the list of servers configured in the system.

Use one of the below DNS modes:

GetRemoteIPs Method (SecureBlackbox_Utils Class)

Resolves IP addresses available for a hostname.

Object Oriented Interface

public function doGetRemoteIPs($hostname, $ipv4, $ipv6, $dnsmode, $dnsservers, $timeout);

Procedural Interface

secureblackbox_utils_do_getremoteips($res, $hostname, $ipv4, $ipv6, $dnsmode, $dnsservers, $timeout);

Remarks

Use this method to resolve all IP addresses available for the chosen hostname using the provided DNS settings. Use the Timeout setting to specify maximal resolution time. The DNSServer parameter lists the addresses of DNS servers to use for address resolution, separated with commas or semicolons. If an empty server list is provided, the component will use the list of servers configured in the system.

Use one of the below DNS modes:

GetValueByName Method (SecureBlackbox_Utils Class)

Returns the value from the (name, value) pair list for the requested name.

Object Oriented Interface

public function doGetValueByName($name);

Procedural Interface

secureblackbox_utils_do_getvaluebyname($res, $name);

Remarks

Use this method to obtain a matching value for the requested Name in the NameValuePairs list.

HexDecode Method (SecureBlackbox_Utils Class)

Decodes a hex-encoded string into a byte array.

Object Oriented Interface

public function doHexDecode($value);

Procedural Interface

secureblackbox_utils_do_hexdecode($res, $value);

Remarks

Use this method to decode hex- (base16-) encoded strings to byte arrays. byte[] buf = utils.HexDecode("48656C6C6F2C20776F726C6421");

HexEncode Method (SecureBlackbox_Utils Class)

Encodes a byte array to hex string.

Object Oriented Interface

public function doHexEncode($bytes);

Procedural Interface

secureblackbox_utils_do_hexencode($res, $bytes);

Remarks

Use this method to encode a byte array, passed as Bytes, to a hex (base16) string.

IndexOfName Method (SecureBlackbox_Utils Class)

Returns the index of the (name, value) pair in the list for the requested Name.

Object Oriented Interface

public function doIndexOfName($name);

Procedural Interface

secureblackbox_utils_do_indexofname($res, $name);

Remarks

Use this method to obtain the index of the (Name, Value) object in NameValuePairs list.

LoadMultipartFromBytes Method (SecureBlackbox_Utils Class)

Loads a multipart message from the specified byte array to MultipartMessage .

Object Oriented Interface

public function doLoadMultipartFromBytes($contenttype, $data);

Procedural Interface

secureblackbox_utils_do_loadmultipartfrombytes($res, $contenttype, $data);

Remarks

Use this method to load a multipart message from a byte array to MultipartMessage. You need to provide the content of the Content-Type header field together with the multipart body stored in the byte array.

After the data is loaded, you can get the data of each part by calling GetPartToBytes/GetPartToFile/GetPartToStream methods.

While loading data, the parts data is stored in temporary files/streams. If the TempPath config property is not empty, the parts data is stored to temporary files in that folder, otherwise the data is stored in memory streams.

LoadMultipartFromFile Method (SecureBlackbox_Utils Class)

Loads a multipart message from the specified file to MultipartMessage .

Object Oriented Interface

public function doLoadMultipartFromFile($contenttype, $filename);

Procedural Interface

secureblackbox_utils_do_loadmultipartfromfile($res, $contenttype, $filename);

Remarks

Use this method to load a multipart message from a file to MultipartMessage. You need to provide the content of the Content-Type header field together with the multipart body stored in the file.

After the file is loaded, you can get the data of each part by calling GetPartToBytes/GetPartToFile/GetPartToStream methods.

While loading data, the parts data is stored in temporary files/streams. If the TempPath config property is not empty, the parts data is stored to temporary files in that folder, otherwise the data is stored in memory streams.

LoadNameValuePairs Method (SecureBlackbox_Utils Class)

Loads a list of (name, value) pairs from a string.

Object Oriented Interface

public function doLoadNameValuePairs($data, $format, $namevalueseparator, $pairseparator, $trimvalues);

Procedural Interface

secureblackbox_utils_do_loadnamevaluepairs($res, $data, $format, $namevalueseparator, $pairseparator, $trimvalues);

Remarks

Use this method to load a list of (name, value) pairs to NameValuePairs from a string. Provide one of the known formats via Format, and optionally pass the separators using NameValueSeparator and PairSeparator parameters.

The following pre-defined pair list formats are currently supported:

• rdn: a textual distinguished name encoding (/C=US/S=NC/O=Big Company)
• rdnbinary: a hex-encoded DER encoding of the ASN.1 RelativeDistinguishedName object

If one of these formats is used, the separator parameters are ignored.

OidToString Method (SecureBlackbox_Utils Class)

Converts a binary-encoded ASN.1 OID to its string representation.

Object Oriented Interface

public function doOidToString($bytes);

Procedural Interface

secureblackbox_utils_do_oidtostring($res, $bytes);

Remarks

Use this method to convert binary-encoded OIDs (object identifiers) to their dotted string representations. byte[] oid_bin = new byte[] { 0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x01, 0x06 }; string oid_str = utils.OidToString(oid_bin); Console.WriteLine(oid_str); // prints 2.16.840.1.101.3.4.1.6

RemoveNameValuePair Method (SecureBlackbox_Utils Class)

Remove a (name, value) pair by name.

Object Oriented Interface

public function doRemoveNameValuePair($name);

Procedural Interface

secureblackbox_utils_do_removenamevaluepair($res, $name);

Remarks

Use this method to remove the (Name, Value) pair from the NameValuePairs list.

Reset Method (SecureBlackbox_Utils Class)

Resets the class settings.

Object Oriented Interface

public function doReset();

Procedural Interface

secureblackbox_utils_do_reset($res);

Remarks

Reset is a generic method available in every class.

SaveMultipartContentType Method (SecureBlackbox_Utils Class)

Returns the value for Content-Type field.

Object Oriented Interface

public function doSaveMultipartContentType();

Procedural Interface

secureblackbox_utils_do_savemultipartcontenttype($res);

Remarks

Call this method to get a value for Content-Type field after calling SaveMultipartToBytes or SaveMultipartToFile or SaveMultipartToStream.

SaveMultipartToBytes Method (SecureBlackbox_Utils Class)

Saves the parts contained in MultipartMessage to a byte array.

Object Oriented Interface

public function doSaveMultipartToBytes($multipartmode);

Procedural Interface

secureblackbox_utils_do_savemultiparttobytes($res, $multipartmode);

Remarks

Use this method to store MultipartMessage to a temporary byte array.

Supported values for MultipartMode are:

To send the stored data to an HTTP server, follow the steps below:

1. Call SaveMultipartContentType method and assign the returned value to ContentType field of RequestParameters> property
2. Call PostBytes> method and pass the array to it

SaveMultipartToFile Method (SecureBlackbox_Utils Class)

Saves the parts contained in MultipartMessage to the file.

Object Oriented Interface

public function doSaveMultipartToFile($multipartmode, $filename);

Procedural Interface

secureblackbox_utils_do_savemultiparttofile($res, $multipartmode, $filename);

Remarks

Use this method to store MultipartMessage to a temporary file.

Supported values for MultipartMode are:

FileName is the name of the target file for the multipart message.

To send the stored data to an HTTP server, follow the steps below:

1. Call SaveMultipartContentType method and assign the returned value to ContentType field of RequestParameters> property
2. Call PostFile> method and pass the filename to it

SaveNameValuePairs Method (SecureBlackbox_Utils Class)

Serializes the (name, value) pair list to a string.

Object Oriented Interface

public function doSaveNameValuePairs($format, $namevalueseparator, $pairseparator);

Procedural Interface

secureblackbox_utils_do_savenamevaluepairs($res, $format, $namevalueseparator, $pairseparator);

Remarks

Use this method to save the contents of NameValuePairs to a string. Provide the desired format through the Format parameter, and entry separators (if required) via NameValueSeparator and PairSeparator parameters.

The following pre-defined pair list formats are currently supported:

• rdn: a textual distinguished name encoding (/C=US/S=NC/O=Big Company)
• rdnbinary: a hex-encoded DER encoding of the ASN.1 RelativeDistinguishedName object

If one of these formats is used, the separator parameters are ignored.

SetValueByName Method (SecureBlackbox_Utils Class)

Adds or updates the (name, value) pair by a name.

Object Oriented Interface

public function doSetValueByName($name, $value);

Procedural Interface

secureblackbox_utils_do_setvaluebyname($res, $name, $value);

Remarks

This method updates the existing (Name, Value) pair with a new value, or adds a new pair if no such pair existed in NameValuePairs list.

StringDecode Method (SecureBlackbox_Utils Class)

Converts a byte array to a string using a chosen encoding.

Object Oriented Interface

public function doStringDecode($bytes, $encoding);

Procedural Interface

secureblackbox_utils_do_stringdecode($res, $bytes, $encoding);

Remarks

Use this method to convert a byte array to a string using the required text encoding. The following encodings are currently supported: utf-8, utf16.

Leave Encoding empty to use the default code page configured in the system.

StringEncode Method (SecureBlackbox_Utils Class)

Encodes a string to a byte array using a chosen character encoding.

Object Oriented Interface

public function doStringEncode($value, $encoding);

Procedural Interface

secureblackbox_utils_do_stringencode($res, $value, $encoding);

Remarks

Use this method to convert a string to a byte array using the provided text encoding. The following encodings are currently supported: utf-8, utf16.

Leave Encoding empty to use the default code page configured in the system.

StringToDate Method (SecureBlackbox_Utils Class)

Converts a date represented by a string to a respective Date object.

Object Oriented Interface

public function doStringToDate($value);

Procedural Interface

secureblackbox_utils_do_stringtodate($res, $value);

Remarks

Use this method to convert a date string that you obtained from a SecureBlackbox component property or method to a platform date object.

StringToOid Method (SecureBlackbox_Utils Class)

Converts string OID representation to an ASN.1 byte array.

Object Oriented Interface

public function doStringToOid($value);

Procedural Interface

secureblackbox_utils_do_stringtooid($res, $value);

Remarks

Use this method to convert an OID represented with a dotted string to the respective ASN.1 representation. string oid_str = "2.16.840.1.101.3.4.1.6"; byte[] oid_buf = utils.StringToOid(oid_str);

UrlDecode Method (SecureBlackbox_Utils Class)

Decodes a URLEncoded string back into its original form.

Object Oriented Interface

public function doUrlDecode($value);

Procedural Interface

secureblackbox_utils_do_urldecode($res, $value);

Remarks

Use this method to decode the URLEncoded Value back to its original representation.

UrlEncode Method (SecureBlackbox_Utils Class)

Encodes the provided string using URLEncode.

Object Oriented Interface

public function doUrlEncode($value);

Procedural Interface

secureblackbox_utils_do_urlencode($res, $value);

Remarks

Use this method to encode Value using URL Encoding (percent encoding), as defined in RFC 3986.

Error Event (SecureBlackbox_Utils Class)

Informs about errors during cryptographic operations.

Object Oriented Interface

public function fireError($param);

Procedural Interface

secureblackbox_utils_register_callback($res, 1, array($this, 'fireError'));

Parameter List

 'errorcode'
 'description'

Remarks

Class fires this event if an error happens during a cryptographic operation.

ErrorCode contains an error code and Description contains a textual description of the error that happened.

Notification Event (SecureBlackbox_Utils Class)

This event notifies the application about an underlying control flow event.

Object Oriented Interface

public function fireNotification($param);

Procedural Interface

secureblackbox_utils_register_callback($res, 2, array($this, 'fireNotification'));

Parameter List

 'eventid'
 'eventparam'

Remarks

The class fires this event to let the application know about some event, occurrence, or milestone in the class. For example, it may fire to report completion of the document processing. The list of events being reported is not fixed, and may be flexibly extended over time.

The unique identifier of the event is provided in the EventID parameter. EventParam contains any parameters accompanying the occurrence. Depending on the type of the class, the exact action it is performing, or the document being processed, one or both may be omitted.

Config Settings (Utils Class)

The class accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

Utils Config Settings

Base Config Settings

Trappable Errors (Utils Class)

Utils Errors