Device Connection Criteria

Before attempting to connect to devices such as card readers and printers, the integrator has the option to set the specific connection criteria to use during the device search. This will ensure that Commerce SDK will only attempt to search for the devices specified by the integrator, which will result in a faster connection to the device. The connection criteria are also used for specifying the details of a connection over an IP channel, such as the IP address, port, and encryption type.

Setting the connection configuration is only required if IP connection parameters need to be specified. If not set, Commerce SDK will search for all other supported devices by default.

Note that this method is only used to setup the connection configuration that will be used for future device searches. For an example of performing an actual device search that will use the connection configuration set by this method, see [doclink id=“card-reader-connection”]Card Reader Connection[/doclink].

Timings: CSDK Find Devices vs CSDK 4.1

Prerequisites for IP Configuration

1. Configure the card reader to accept plain data transfer over IP.
2. Establish IP-based communication channel between application and card reader.
3. Enable SSL on the card reader (refer to the Client Certificate for IP Communication section of the appropriate integration method).

Code Samples

CWS

Request

Response

Example

Request

{
  "method" : "setDeviceConnectionConfiguration",
  "requestId" : "1253881538",
  "targetType" : "api",
  "parameters" : {
    "connectionCriteria" : {
      "providerTypes" : ["INGENICO_RBA_UPP", "STAR"],
      "connectionTypes" : ["USB", "IP"],
      "deviceTypes" : ["CARD_READER", "PRINTER"],
      "inetAddress" : {
        "host" : "192.168.1.137",
        "port" : 12000,
        "encryptionScheme" : "NONE"/"TLS_12"
      }
    }
  }
}

Response

{
  "requestId" : "1253881538",
  "statusDetails" : "REQUEST_ACCEPTED",
  "data" : {
    "completed" : true
  }
}

getDeviceConnectionConfiguration

There is additional request/response for getDeviceConnectionConfiguration:

Request

Response

Request

{
  "method" : "getDeviceConnectionConfiguration",
  "requestId" : "1253881539",
  "targetType" : "api"
}

Response

{
  "requestId" : "1253881539",
  "statusDetails" : "REQUEST_ACCEPTED",
  "data" : {
    "completed" : true
    "connectionCriteria" : {
      "providerTypes" : ["INGENICO_RBA_UPP", "STAR"],
      "connectionTypes" : ["USB", "IP"],
      "deviceTypes" : ["CARD_READER", "PRINTER"],
      "inetAddress" : {
        "host" : "192.168.1.137",
        "port" : 12000,
        "encryptionScheme" : "TLS_12"
      }
    }
  }
}

Java

Set Up

1. Retrieve an instance of ECLConnectionConfiguration.

   The call to getInstance() returns a reference to a global singleton object, so you cannot have multiple ECLConnectionConfiguration at the same time.

2. Create an ECLConnectionCriteria and set it.

3. You can get the currently set ECLConnectionCriteria at any time.

Code Sample

ECLConnectionConfiguration config = ECLConnectionConfiguration.getInstance();
EnumSet<ECLDeviceProviderType> providerTypes = EnumSet.of(ECLDeviceProviderType.INGENICO_RBA_UPP, ECLDeviceProviderType.ROAM_RUA, ECLDeviceProviderType.STAR);
EnumSet<ECLConnectionType> connectionTypes = EnumSet.of(ECLConnectionType.AUDIO, ECLConnectionType.BT, ECLConnectionType.IP);
EnumSet<ECLDeviceType> deviceTypes = EnumSet.of(ECLDeviceType.CARD_READER, ECLDeviceType.PRINTER);
ECLConnectionCriteria.Builder criteriaBuilder = new ECLConnectionCriteria.Builder();
ECLConnectionCriteria criteria = criteriaBuilder
    .setEnabledDeviceProviderTypes(providerTypes)
    .setEnabledConnectionTypes(connectionTypes)
    .setEnabledDeviceTypes(deviceTypes)
    .setInetAddress(new ECLInetAddress(ip, port, ECLEncryptionScheme.TLS_12))
    .setConnectionParameters(connectionParameters)
    .setClientKeystoreDate(keystoreDateYYYYMMDD)
    .build();

try
{
     config.setConnectionCriteria(criteria);
}
catch (ECLCommerceException ece)
{
     showError("Connection Configuration Exception", "Error trying to set connection criteria: %s", ece.getCode().name());
}

//get
ECLConnectionCriteria currentCriteria = config.getConnectionCriteria();

Reset Connection Configuration

You can reset the connection configuration to the default, which will search for all supported devices.

try
{
     config.setConnectionCriteria(null);
}
catch (ECLCommerceException ece)
{
     //should not get this when setting to null
}

Objective-C (iOS)

Set Up

1. Use ECLConnectionConfiguration:sharedInstance to retrieve the global ECLConnectionConfiguration instance. The call to ECLConnectionConfiguration:sharedInstance returns a reference to a global singleton object, so you cannot have multiple ECLConnectionConfiguration at the same time.
2. Create an ECLConnectionCriteria object and set it.
3. You can get the currently set ECLConnectionCriteria at any time, using ECLConnectionConfiguration:getConnectionCriteria:.

Code Sample

// Get ECLConnectionConfiguration global instance...
ECLConnectionConfiguration *connectionConfiguration = [ECLConnectionConfiguration sharedInstance];

// Define what device providers, connection types, and device types you wish to search for...
NSSet <NSNumber *> *enabledDeviceProviderTypes = [NSSet setWithArray:@[@(ECLDeviceProviderType_INGENICO_RBA_UPP),@(ECLDeviceProviderType_ROAM_RUA),@(ECLDeviceProviderType_STAR)]];
NSSet <NSNumber *> *enabledConnectionTypes = [NSSet setWithArray:@[@(ECLConnectionType_AUDIO),@(ECLConnectionType_BT),@(ECLConnectionType_IP)]];
NSSet <NSNumber *> *enabledDeviceTypes = [NSSet setWithArray:@[@(ECLDeviceType_CARD_READER),@(ECLDeviceType_PRINTER)]];
ECLConnectionCriteria *criteria = [ECLConnectionCriteria makeWithBuilder:^(ECLConnectionCriteriaBuilder *builder) {
    builder.enabledDeviceProviderTypes = enabledDeviceProviderTypes;
    builder.enabledConnectionTypes = enabledConnectionTypes;
    builder.enabledDeviceTypes = enabledDeviceTypes;
    builder.inetAddress = [[ECLInetAddress alloc] initWithHostAndClientCertificateInfo:@"192.168.1.1"
        port:@(12000)
        encryptionScheme:ECLEncryptionScheme_TLS_12
        validClientPFXFilePath:certificateKeystorePath
        validClientPfxFilePasscode:certificateKeystorePassword
        validClientPfxFileDate:certificateKeystoreDate
        expiredClientPFXFilePath:expiredCertificateKeystorePath
        validPfxFilePasscode:expiredCertificateKeystorePasscode
    ];
}];

// Set the new search criteria for the global ECLConnectionConfiguration instance...
ECLError *error = [connectionConfiguration setConnectionCriteria:criteria];
if (error == nil)
{
    // No error? Then, the connection criteria has been successfully set!
}
else
{
    // If an error is returned, please see documentation for each possible ECLConnectionConfiguration:setConnectionCriteria: error (e.g. ECLConnectionCriteriaEmptyDeviceProviderTypes).
}

Reset Connection Configuration

You can reset the connection configuration to the default, just like in Java, which will search for all supported devices.

// Since the criteria is set to the default, ECLConnectionConfiguration:setConnectionCriteria: will always return nil.
ECLError *error = [connectionConfiguration setConnectionCriteria:nil];

C#

private void MySetDeviceConfigComplete(SetDeviceConfigResults crc)
{
     String statusDetails = crc.StatusDetails;
     if ((null != statusDetails) && (0 < statusDetails.Length))
         Log("Status Details: " + statusDetails);

     String error = crc.Error;
     if ((null != error) && (0 < error.Length))
         Log("Error: " + error);
     else
         Log("No error");
}

DeviceConnectionCriteria connCriteria = new DeviceConnectionCriteria();
connCriteria.providerTypes = new string[] { DeviceProviderType.INGENICO_RBA_UPP, DeviceProviderType.STAR };
connCriteria.connectionTypes = new string[] { ConnectionType.USB, ConnectionType.IP };
connCriteria.deviceTypes = new string[] { DeviceType.CARD_READER, DeviceType.PRINTER };
connCriteria.inetAddress = new InetAddress("121.121.12.12", 12000, EncryptionScheme.TLS_12);

DeviceConfigArgs args = new DeviceConfigArgs();
args.connectionCriteria = connCriteria;
m_CWS.StartSetDeviceConfig(args, MyNotifyCWSEvent, MySetDeviceConfigComplete);


// Get
private void MyGetDeviceConfigComplete(GetDeviceConfigResults crc)
{
     DeviceConnectionCriteria connCriteria = crc.GetConnectionCriteria;
}

m_CWS.StartGetDeviceConfig(MyNotifyCWSEvent, MyGetDeviceConfigComplete);