Utils Module

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

SecureBlackbox.Utils

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.

Property List

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

Method List

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

Event List

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

Config Settings

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

MultipartMessage Property (Utils Module)

Lists the content of the multipart message.

Syntax

• Swift
• Objective-C

public var multipartMessage: Array<MultipartMessagePart> {
  get {...}
}

@property (nonatomic,readwrite,assign,getter=multipartPartCount,setter=setMultipartPartCount:) int multipartPartCount;

- (int)multipartPartCount;
- (void)setMultipartPartCount :(int)newMultipartPartCount;

- (NSString*)multipartPartContentDescription:(int)multipartPartIndex;
- (void)setMultipartPartContentDescription:(int)multipartPartIndex :(NSString*)newMultipartPartContentDescription;

- (NSString*)multipartPartContentDisposition:(int)multipartPartIndex;
- (void)setMultipartPartContentDisposition:(int)multipartPartIndex :(NSString*)newMultipartPartContentDisposition;

- (NSString*)multipartPartContentID:(int)multipartPartIndex;
- (void)setMultipartPartContentID:(int)multipartPartIndex :(NSString*)newMultipartPartContentID;

- (NSString*)multipartPartContentTransferEncoding:(int)multipartPartIndex;
- (void)setMultipartPartContentTransferEncoding:(int)multipartPartIndex :(NSString*)newMultipartPartContentTransferEncoding;

- (NSString*)multipartPartContentType:(int)multipartPartIndex;
- (void)setMultipartPartContentType:(int)multipartPartIndex :(NSString*)newMultipartPartContentType;

- (NSString*)multipartPartCustomHeaders:(int)multipartPartIndex;
- (void)setMultipartPartCustomHeaders:(int)multipartPartIndex :(NSString*)newMultipartPartCustomHeaders;

- (NSString*)multipartPartFieldName:(int)multipartPartIndex;
- (void)setMultipartPartFieldName:(int)multipartPartIndex :(NSString*)newMultipartPartFieldName;

- (NSString*)multipartPartFieldValue:(int)multipartPartIndex;
- (void)setMultipartPartFieldValue:(int)multipartPartIndex :(NSString*)newMultipartPartFieldValue;

- (NSString*)multipartPartFilename:(int)multipartPartIndex;
- (void)setMultipartPartFilename:(int)multipartPartIndex :(NSString*)newMultipartPartFilename;

- (long long)multipartPartHandle:(int)multipartPartIndex;
- (void)setMultipartPartHandle:(int)multipartPartIndex :(long long)newMultipartPartHandle;

Default Value

""

Remarks

This property provides access to all parts contained in or to be added to the multipart message.

NameValuePairs Property (Utils Module)

A current list of (name, value) pairs.

Syntax

• Swift
• Objective-C

public var nameValuePairs: Array<StringNameValuePair> {
  get {...}
}

@property (nonatomic,readwrite,assign,getter=nameValuePairCount,setter=setNameValuePairCount:) int nameValuePairCount;

- (int)nameValuePairCount;
- (void)setNameValuePairCount :(int)newNameValuePairCount;

- (NSString*)nameValuePairCategory:(int)nameValuePairIndex;
- (void)setNameValuePairCategory:(int)nameValuePairIndex :(NSString*)newNameValuePairCategory;

- (int)nameValuePairFormat:(int)nameValuePairIndex;
- (void)setNameValuePairFormat:(int)nameValuePairIndex :(int)newNameValuePairFormat;

- (NSString*)nameValuePairName:(int)nameValuePairIndex;
- (void)setNameValuePairName:(int)nameValuePairIndex :(NSString*)newNameValuePairName;

- (NSString*)nameValuePairValue:(int)nameValuePairIndex;
- (void)setNameValuePairValue:(int)nameValuePairIndex :(NSString*)newNameValuePairValue;

Default Value

""

Remarks

Use this property to access the elements of the (name, value) pair list. Use LoadNameValuePairs and SaveNameValuePairs methods to serialize and deserialize the list to a string, and methods such as SetValueByName or RemoveNameValuePair to manage the list.

AddPartFromBytes Method (Utils Module)

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

Syntax

• Swift
• Objective-C

public func addPartFromBytes(data: Data) throws -> Int32

- (int)addPartFromBytes:(NSData*)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 (Utils Module)

Adds a new part to MultipartMessage from the specified file.

Syntax

• Swift
• Objective-C

public func addPartFromFile(filename: String) throws -> Int32

- (int)addPartFromFile:(NSString*)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 (Utils Module)

Decodes a base64 string to a byte array.

Syntax

• Swift
• Objective-C

public func base64Decode(value: String, useURLEncoding: Bool) throws -> Data

- (NSData*)base64Decode:(NSString*)value :(BOOL)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 (Utils Module)

Encodes a byte array in base64.

Syntax

• Swift
• Objective-C

public func base64Encode(bytes: Data, useURLEncoding: Bool) throws -> String

- (NSString*)base64Encode:(NSData*)bytes :(BOOL)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 (Utils Module)

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

Syntax

• Swift
• Objective-C

public func base64EncodeLines(bytes: Data, lineLen: Int32) throws -> String

- (NSString*)base64EncodeLines:(NSData*)bytes :(int)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 (Utils Module)

Sets or retrieves a configuration setting.

Syntax

• Swift
• Objective-C

public func config(configurationString: String) throws -> String

- (NSString*)config:(NSString*)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 (Utils Module)

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

Syntax

• Swift
• Objective-C

public func dateToString(value: Date) throws -> String

- (NSString*)dateToString:(NSDate*)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 (Utils Module)

Performs an additional action.

Syntax

• Swift
• Objective-C

public func doAction(actionID: String, actionParams: String) throws -> String

- (NSString*)doAction:(NSString*)actionID :(NSString*)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;....

GetLocalDNSName Method (Utils Module)

Returns the DNS name of the local system.

Syntax

• Swift
• Objective-C

public func getLocalDNSName() throws -> String

- (NSString*)getLocalDNSName;

Remarks

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

GetLocalIP Method (Utils Module)

Returns the primary IP address of the local system.

Syntax

• Swift
• Objective-C

public func getLocalIP(iPv6: Bool) throws -> String

- (NSString*)getLocalIP:(BOOL)IPv6;

Remarks

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

GetLocalIPs Method (Utils Module)

Returns a list of local IP addresses.

Syntax

• Swift
• Objective-C

public func getLocalIPs(iPv4: Bool, iPv6: Bool) throws -> String

- (NSString*)getLocalIPs:(BOOL)IPv4 :(BOOL)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 (Utils Module)

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

Syntax

• Swift
• Objective-C

public func getPartToBytes(index: Int32) throws -> Data

- (NSData*)getPartToBytes:(int)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 (Utils Module)

Saves the data from the specified part to a file.

Syntax

• Swift
• Objective-C

public func getPartToFile(index: Int32, filename: String) throws -> Void

- (void)getPartToFile:(int)index :(NSString*)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 (Utils Module)

Gets the IP address of a remote host.

Syntax

• Swift
• Objective-C

public func getRemoteIP(hostName: String, iPv6: Bool, dnsMode: Int32, dnsServers: String, timeout: Int32) throws -> String

- (NSString*)getRemoteIP:(NSString*)hostName :(BOOL)IPv6 :(int)DNSMode :(NSString*)DNSServers :(int)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 (Utils Module)

Resolves IP addresses available for a hostname.

Syntax

• Swift
• Objective-C

public func getRemoteIPs(hostName: String, iPv4: Bool, iPv6: Bool, dnsMode: Int32, dnsServers: String, timeout: Int32) throws -> String

- (NSString*)getRemoteIPs:(NSString*)hostName :(BOOL)IPv4 :(BOOL)IPv6 :(int)DNSMode :(NSString*)DNSServers :(int)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 (Utils Module)

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

Syntax

• Swift
• Objective-C

public func getValueByName(name: String) throws -> String

- (NSString*)getValueByName:(NSString*)name;

Remarks

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

HexDecode Method (Utils Module)

Decodes a hex-encoded string into a byte array.

Syntax

• Swift
• Objective-C

public func hexDecode(value: String) throws -> Data

- (NSData*)hexDecode:(NSString*)value;

Remarks

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

HexEncode Method (Utils Module)

Encodes a byte array to hex string.

Syntax

• Swift
• Objective-C

public func hexEncode(bytes: Data) throws -> String

- (NSString*)hexEncode:(NSData*)bytes;

Remarks

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

IndexOfName Method (Utils Module)

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

Syntax

• Swift
• Objective-C

public func indexOfName(name: String) throws -> Int32

- (int)indexOfName:(NSString*)name;

Remarks

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

LoadMultipartFromBytes Method (Utils Module)

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

Syntax

• Swift
• Objective-C

public func loadMultipartFromBytes(contentType: String, data: Data) throws -> Void

- (void)loadMultipartFromBytes:(NSString*)contentType :(NSData*)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 (Utils Module)

Loads a multipart message from the specified file to MultipartMessage .

Syntax

• Swift
• Objective-C

public func loadMultipartFromFile(contentType: String, filename: String) throws -> Void

- (void)loadMultipartFromFile:(NSString*)contentType :(NSString*)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 (Utils Module)

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

Syntax

• Swift
• Objective-C

public func loadNameValuePairs(data: String, format: String, nameValueSeparator: String, pairSeparator: String, trimValues: Bool) throws -> Void

- (void)loadNameValuePairs:(NSString*)data :(NSString*)format :(NSString*)nameValueSeparator :(NSString*)pairSeparator :(BOOL)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

OidToString Method (Utils Module)

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

Syntax

• Swift
• Objective-C

public func oidToString(bytes: Data) throws -> String

- (NSString*)oidToString:(NSData*)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 (Utils Module)

Remove a (name, value) pair by name.

Syntax

• Swift
• Objective-C

public func removeNameValuePair(name: String) throws -> Bool

- (BOOL)removeNameValuePair:(NSString*)name;

Remarks

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

SaveMultipartContentType Method (Utils Module)

Returns the value for Content-Type field.

Syntax

• Swift
• Objective-C

public func saveMultipartContentType() throws -> String

- (NSString*)saveMultipartContentType;

Remarks

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

SaveMultipartToBytes Method (Utils Module)

Saves the parts contained in MultipartMessage to a byte array.

Syntax

• Swift
• Objective-C

public func saveMultipartToBytes(multipartMode: Int32) throws -> Data

- (NSData*)saveMultipartToBytes:(int)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 (Utils Module)

Saves the parts contained in MultipartMessage to the file.

Syntax

• Swift
• Objective-C

public func saveMultipartToFile(multipartMode: Int32, filename: String) throws -> Void

- (void)saveMultipartToFile:(int)multipartMode :(NSString*)filename;

Remarks

Use this method to store MultipartMessage to a temporary file.

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 PostFile> method and pass the filename to it

SaveNameValuePairs Method (Utils Module)

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

Syntax

• Swift
• Objective-C

public func saveNameValuePairs(format: String, nameValueSeparator: String, pairSeparator: String) throws -> String

- (NSString*)saveNameValuePairs:(NSString*)format :(NSString*)nameValueSeparator :(NSString*)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

SetValueByName Method (Utils Module)

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

Syntax

• Swift
• Objective-C

public func setValueByName(name: String, value: String) throws -> Int32

- (int)setValueByName:(NSString*)name :(NSString*)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 (Utils Module)

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

Syntax

• Swift
• Objective-C

public func stringDecode(bytes: Data, encoding: String) throws -> String

- (NSString*)stringDecode:(NSData*)bytes :(NSString*)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 (Utils Module)

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

Syntax

• Swift
• Objective-C

public func stringEncode(value: String, encoding: String) throws -> Data

- (NSData*)stringEncode:(NSString*)value :(NSString*)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 (Utils Module)

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

Syntax

• Swift
• Objective-C

public func stringToDate(value: String) throws -> Date

- (NSDate*)stringToDate:(NSString*)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 (Utils Module)

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

Syntax

• Swift
• Objective-C

public func stringToOid(value: String) throws -> Data

- (NSData*)stringToOid:(NSString*)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 (Utils Module)

Decodes a URLEncoded string back into its original form.

Syntax

• Swift
• Objective-C

public func urlDecode(value: String) throws -> String

- (NSString*)urlDecode:(NSString*)value;

Remarks

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

UrlEncode Method (Utils Module)

Encodes the provided string using URLEncode.

Syntax

• Swift
• Objective-C

public func urlEncode(value: String) throws -> String

- (NSString*)urlEncode:(NSString*)value;

Remarks

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

Error Event (Utils Module)

Informs about errors during cryptographic operations.

Syntax

• Swift
• Objective-C

func onError(errorCode: Int32, description: String)

- (void)onError:(int)errorCode :(NSString*)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 (Utils Module)

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

Syntax

• Swift
• Objective-C

func onNotification(eventID: String, eventParam: String)

- (void)onNotification:(NSString*)eventID :(NSString*)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.

MultipartMessagePart Type

Represents a part of a multipart message transferred over HTTP.

Remarks

This type contains all information about a single part in a multipart message.

Fields

Constructors

public init()

Creates a new part of multipart message.

StringNameValuePair Type

A simple name-value pair object.

Remarks

The class represents a name-value string pair used in a variety of network components.

Fields

Constructors

public init(name: , value: )

Creates a name-value pair from a name and a value.

public init()

Creates an empty name-value object.

Config Settings (Utils Module)

Utils Config Settings

Base Config Settings

Trappable Errors (Utils Module)

Utils Errors