SocketCam¶

The application receives the decoded data with the same APIs that are used for the physical readers and they can also be used to manage some of the SocketCam properties the same way you would for a physical reader.

There are 2 requirements to use SocketCam:

The application needs to enable SocketCam.
A software trigger button must be added in the UI to trigger a read from SocketCam using the camera.

CaptureSDK is designed to handle multiple devices at once. An application can enable SocketCam and can still use a physical scanner without any conflicts.

In some deployments when such configuration exists, often the application hides the software trigger button as soon as a physical scanner is connected, and vice-versa when the physical scanner disconnects, the application shows the software trigger button to be able to use the device camera as scanner.

SocketCam is implemented as an extension of CaptureSDK. It has to be used in the application context.

Note

For deployment that has CaptureSDK implemented in a service layer, it is important that the SocketCam CaptureExtension stays in the context of the application. CaptureSDK can still reside in a different context. This is mainly for getting the camera access from the application and to be able to display the viewfinder in the context of the application.

Enabling SocketCam¶

Enabling SocketCam is a 2 step process.

Step 1: Start Capture Extension¶

The first step of using SocketCam in an application is to start the SocketCam Capture extension by invoking the CaptureExtension start() method. This requires the following mandatory parameters:

Context : this should be the Application context
CaptureSDK Client Handle : this is an integer value that can be retrieved by calling getHandle() from CaptureSDK client object. The CaptureSDK client object can be retrieved in the ConnectionStateEvent handler by calling event.getClient().

This identifies and connects the CaptureExtension to the CaptureSDK client object.

There are some optional parameters:

Extension scope : tells CaptureSDK service if the devices of the Capture Extension can be used by any applications connected to the service, or only by the application that has opened the service with the specified capture client handle.
There are two possible values:
- LOCAL : Can be used only by application that opened the client. This is the default value and recommended value.
- GLOBAL : Can be used by any application that is interested in using the extension
SetListener : this listener has two call back methods
- onExtensionStateChanged : Called when the extension is started or stopped
- onError : Called when there is an error while starting the extension
App Credentials : an AppKey is required for starting the Capture extension. The setup is the same as for opening a Capture client. If you are using the same context for opening capture client, you can skip this section
SetCustomViewListener : this listener is set when the application wants use the custom viewfinder by using SocketCamFragment in one of its own Activities. If this listener is not set then CaptureSDK will launch the default viewfinder Activity in full screen.

Start SocketCam Capture Extension¶

public void startSocketCamExtension() {

    captureExtension = new CaptureExtension.Builder()
        .setContext(this)
        .setClientHandle(mCaptureClient.getHandle())
        .setListener(mOnErrorListener)
        .build().start();
    }

This step starts the CaptureExtension and returns the CaptureExtension instance, which can then be used to stop the CaptureExtension when the application terminates.

Step 2: Enable SocketCam¶

The second step is to the set SocketCamStatus property value to ‘ENABLE’. This is a persistent setting that can be set during the first launch of the application.

Enable SocketCam¶

public void updateSocketCamStatus(View view) {
        if(mCaptureClient == null || mCaptureExtension == null) {
            return;
        }

        byte status = SocketCamStatus.ENABLE;
        mCaptureClient.setSocketCamStatus(status, mSetPropertyCallback);
    }

mSetPropertyCallback is an implementation of the PropertyCallback.

Once the SocketCamStatus is enabled then the Device Arrival Event is fired and it is ready for the application to use it. See details of Device Arrival Event are here.

Using SocketCam with default ViewFinder¶

Now the application is ready to use the camera as a barcode scanner. Usually an application shows a “Scan” trigger button somewhere in the UI to start scanning for a barcode.

Note

Applications can use physical buttons such as the volume up or down button to act as a trigger button.

The way to start the scanning operation is by sending a set Trigger property. Here are the details to Trigger Scanner

Calling trigger() method will internally call setProperty method. Successful completion of trigger() will launch the default viewfinder Activity. The viewfinder closes once a barcode is scanned. The decoded data are sent in a data event as it does for any other physical scanner.

Trigger continuous mode will launch the scan view and continue to scan barcodes until the view is dismissed by the user

Using SocketCam with custom ViewFinder¶

This option can be used when the application wants to display the viewfinder as part its own Activity. In this case trigger() method will not display the default viewfinder Activity, but instead invoke a callback when the viewfinder is ready to be displayed.

Start by setting the CustomViewListener while starting the extension in Step 1. When this listener has been set, trigger() method will invoke onViewReady() callback. Once the callback is received in the listener, SocketCamFragment is ready to be added to the application’s Activity.

SocketCamFragment needs three parameters. DeviceHandle, which will be returned in onViewReady() callback. DeviceClient from Device Arrival Event. IsScanContinuousMode, a boolean indicating if the SocketCamFragment should be in single scan mode or continuous mode. As the name indicates, when set to true, it will be in continuous scan mode.

Custom ViewFinder¶

mCaptureExtension = new CaptureExtension.Builder()
        .setContext(CustomViewActivity.this)
        .setClientHandle(mCaptureClient.getHandle())
        .setExtensionScope(ExtensionScope.GLOBAL)
        .setListener(mListener)
        .setCustomViewListener(new CaptureExtension.CustomViewListener() {
            @Override
            public void onViewReady(int deviceHandle) {
                runOnUiThread(new Runnable() {
                    @Override
                    public void run() {
                        getSupportFragmentManager().beginTransaction()
                                .add(R.id.socketcam_fragment, SocketCamFragment.newInstance(deviceHandle, mDevice, true))
                                .commit();
                    }
                });
            }
        })
        .build();
mCaptureExtension.start();

Receive Data¶

To receive the data in the activity, subscribe to Data Events. See details of Data Events here.