Click or drag to resize

ConnectionBuilder Class

Builds a Connection from a description string. The description string is used to specify a connection to a specific device over TCP, USB, or Bluetooth® (Windows 10 only).
Inheritance Hierarchy
SystemObject
  Zebra.Sdk.CommConnectionBuilder

Namespace:  Zebra.Sdk.Comm
Assembly:  SdkApi_Desktop (in SdkApi_Desktop.dll) Version: 2.13.898
Syntax
public class ConnectionBuilder

The ConnectionBuilder type exposes the following members.

Methods
  NameDescription
Public methodStatic memberAddConnectionType
Add a connection type to the ConnectionBuilder.
Public methodStatic memberCode exampleBuild
Creates a Connection type based on the contents of descriptionString.
Public methodEquals
Determines whether the specified object is equal to the current object.
(Inherited from Object.)
Public methodGetHashCode
Serves as the default hash function.
(Inherited from Object.)
Public methodGetType
Gets the Type of the current instance.
(Inherited from Object.)
Public methodToString
Returns a string that represents the current object.
(Inherited from Object.)
Top
Remarks

The description string may be of the explicit forms:

"TCP:192.168.1.4:6101" -- creates a TCP connection to the device with IP address 192.168.1.4 on port 6101.
"TCP:192.168.1.4" -- creates a TCP connection to the device with IP address 192.168.1.4 on default port 9100.
"TCP:dnsName:6101" -- creates a TCP connection to the device with 'dnsName' on port 6101.
"TCP:dnsName" -- creates a TCP connection to the device with 'dnsName' on default port 9100.
"TCP_MULTI:192.168.1.4" -- creates a Multichannel TCP connection to the device with '192.168.1.4' using the default ports for both the printing channel(9100) and the status channel(9200).
"TCP_MULTI:192.168.1.4:1234" -- creates a Multichannel TCP connection to the device with '192.168.1.4' using the given port for the printing channel(1234) and the default port for the status channel(9200).
"TCP_MULTI:192.168.1.4:1234:5678" -- creates a Multichannel TCP connection to the device with '192.168.1.4' using the given ports for the printing channel(1234) and the status channel(5678).
"TCP_MULTI:dnsName:1234:5678" -- creates a Multichannel TCP connection to the device with 'dnsName' using the given ports for the printing channel(1234) and the status channel(5678).
"TCP_STATUS:192.168.1.4:1234" -- creates a TCP status only connection to the device with IP address 192.168.1.4 on port 1234.
"TCP_STATUS:192.168.1.4" -- creates a TCP status only connection to the device with IP address 192.168.1.4 on the default status port 9200.
"USB:deviceName" -- creates a USB connection (through the ZebraDesigner driver) to the device with printer name 'deviceName'.
"USB_DIRECT:\\?\usb#vid_0a5f&pid_00bd#qln320#..." -- creates a USB connection (direct) to the device using '\\?\usb#vid_0a5f&pid_00bd#qln320#...' as the USB symbolic name.
"BT:11:22:33:44:55:66" -- creates a Bluetooth® connection to the device using '11:22:33:44:55:66' as the MAC address. (Windows 10 only)
"BT_MULTI:11:22:33:44:55:66" -- creates a multichannel Bluetooth® connection to the device using '11:22:33:44:55:66' as the MAC address. (Link-OS 2.5 or higher for the status channel, Windows 10 only)
"BT_STATUS:11:22:33:44:55:66" -- creates a status only Bluetooth® connection to the device using '11:22:33:44:55:66' as the MAC address. (Link-OS 2.5 or higher, Windows 10 only)

Generic text may also be used to attempt to specify a device. For example a description string of "genericText" will attempt to connect to a device using the following priority:
  • TCP_MULTI
  • TCP
  • TCP_STATUS
  • USB
  • USB_DIRECT
  • BT_MULTI
  • BT
  • BT_STATUS
If you supply the string 'MyString'. This could be interpreted to be either a DNS name, or a USB device name. ConnectionBuilder will attempt to connect to this string given the above priority order. If you supply a more specific string, such as '192.168.2.3', ConnectionBuilder will more efficiently interpret this string as being an IP address and, therefore, only attempt the TCP connections.
Note: Colon (':') characters are not supported in dnsName, friendlyName, uniqueId, deviceName, or genericText fields.

The following is an example of building a connection from a string:
Examples
using System;
using System.Text;
using Zebra.Sdk.Comm;
using Zebra.Sdk.Printer;
using Zebra.Sdk.Printer.Discovery;

public class ConnectionBuilderExample {

    public static void Main(string[] args) {
        UsbDriverlessTest();

        new ConnectionBuilderExample().NonBlockingStatusReportingOverMultichannel("1.2.3.4");
        new ConnectionBuilderExample().SendZplOverTcp("1.2.3.4");
        new ConnectionBuilderExample().SendZplOverUsb("ZDesigner GK420t");

        // Windows 10 only
        new ConnectionBuilderExample().SendZplOverBluetooth("11:22:33:44:55:66");
    }

    private static void UsbDriverlessTest() {
        Console.WriteLine("Discovered USB printer list:\r\n");
        foreach (DiscoveredUsbPrinter printer in UsbDiscoverer.GetZebraUsbPrinters()) {
            Console.WriteLine(printer);
        }
        Console.WriteLine("End USB printer list\r\n");

        Connection imz = null;
        try {
            imz = ConnectionBuilder.Build("\\\\?\\usb#vid_0a5f&pid_00f2#imz220#...");
            imz.Open();

            byte[] hi_return = imz.SendAndWaitForResponse(Encoding.UTF8.GetBytes("~HI"), 5000, 10000, "V");
            Console.WriteLine(Encoding.UTF8.GetString(hi_return));
        } finally {
            if (imz != null) {
                imz.Close();
            }
        }
    }

    private void NonBlockingStatusReportingOverMultichannel(string theIpAddress) {
        Connection thePrinterConn = null;
        try {
            // Instantiate Multichannel connection for simultaneous printing and status reporting at given address
            thePrinterConn = ConnectionBuilder.Build($"TCP_MULTI:{theIpAddress}:9100:9200");

            // Opens the connection - physical connection is established here.
            thePrinterConn.Open();

            // Creates a Link-OS printing with the given connection
            ZebraPrinterLinkOs linkOsPrinter = ZebraPrinterFactory.GetLinkOsPrinter(thePrinterConn);

            // This is sent over the printing channel (9100 by default) and will block the printing channel until the
            // label format is completely sent.
            string labelFormatStartCommand = "^XA";
            linkOsPrinter.SendCommand(labelFormatStartCommand);

            string labelBody = "^FO20,20^A0N,25,25^FDThis is a ZPL test.^FS";
            linkOsPrinter.SendCommand(labelBody);

            // This is sent over the status channel (9200 by default) and will return immediately even though the
            // printing channel is in use.
            // If a TcpConnection were used instead of a MultichannelTcpConnection, this would not be possible.
            PrinterStatus status = linkOsPrinter.GetCurrentStatus();

            Console.WriteLine($"The printer PAUSED state is: {status.isPaused}");

            // Send the end of label command to finish and print the label.
            string labelFormatEndCommand = "^XZ";
            linkOsPrinter.SendCommand(labelFormatEndCommand);
        } catch (ConnectionException e) {
            // Handle communications error here.
            Console.WriteLine(e.ToString());
        } finally {
            // Close the connection to release resources.
            if (thePrinterConn != null) {
                thePrinterConn.Close();
            }
        }
    }

    private void SendZplOverTcp(string theIpAddress) {
        Connection thePrinterConn = null;
        try {
            // Instantiate connection for ZPL TCP port at given address
            thePrinterConn = ConnectionBuilder.Build($"TCP:{theIpAddress}:9100");

            // Open the connection - physical connection is established here.
            thePrinterConn.Open();

            // This example prints "This is a ZPL test." near the top of the label.
            string zplData = "^XA^FO20,20^A0N,25,25^FDThis is a ZPL test.^FS^XZ";

            // Send the data to printer as a byte array.
            thePrinterConn.Write(Encoding.UTF8.GetBytes(zplData));
        } catch (ConnectionException e) {
            // Handle communications error here.
            Console.WriteLine(e.ToString());
        } finally {
            // Close the connection to release resources.
            if (thePrinterConn != null) {
                thePrinterConn.Close();
            }
        }
    }

    private void SendZplOverUsb(string usbDriverName) {
        Connection thePrinterConn = null;
        try {
            // Instantiate USB connection for ZPL printer through its driver
            thePrinterConn = ConnectionBuilder.Build($"USB:{usbDriverName}");

            // Open the connection - physical connection is established here.
            thePrinterConn.Open();

            // This example prints "This is a ZPL test." near the top of the label.
            string zplData = "^XA^FO20,20^A0N,25,25^FDThis is a ZPL test.^FS^XZ";

            // Send the data to printer as a byte array.
            thePrinterConn.Write(Encoding.UTF8.GetBytes(zplData));
        } catch (ConnectionException e) {
            // Handle communications error here.
            Console.WriteLine(e.ToString());
        } finally {
            // Close the connection to release resources.
            if (thePrinterConn != null) {
                thePrinterConn.Close();
            }
        }
    }

    private void SendZplOverBluetooth(string btMacAddress) {
        Connection thePrinterConn = null;
        try {
            // Instantiate a Bluetooth connection
            thePrinterConn = ConnectionBuilder.Build($"BT:{btMacAddress}");

            // Open the connection - physical connection is established here.
            thePrinterConn.Open();

            // This example prints "This is a ZPL test." near the top of the label.
            string zplData = "^XA^FO20,20^A0N,25,25^FDThis is a ZPL test.^FS^XZ";

            // Send the data to printer as a byte array.
            thePrinterConn.Write(Encoding.UTF8.GetBytes(zplData));
        } catch (ConnectionException e) {
            // Handle communications error here.
            Console.WriteLine(e.ToString());
        } finally {
            // Close the connection to release resources.
            if (thePrinterConn != null) {
                thePrinterConn.Close();
            }
        }
    }
}
See Also