GuruxClient component

In this walkthrough, you learn to use Gurux GXCom components (GXCom) in the Visual C++ environment (C++ from now on).

Adding GXCom support to the project

Start Visual C++.
Open the project to which you want to add the GXCom component, or create a new one.
Select Options in Tools menu.
Select Directories tab and change "Show directories for:" to "Executable files".
Add new directory to Directories list. New path is "C:\Program Files\Common Files\Gurux\GXCom".

Select StdAfx.h file, and add following line to the bottom of the file:

	
#include <atlbase.h>
#import "GuruxClient.dll" raw_interfaces_only
using namespace GuruxClient;
#include <afxctl.h> // Needed for AfxConnectionAdvise

Now Gurux Components are ready to be used from C++.

Creating components from C++

Before component can be used in C++, it must be created as follows:

CComPtr<IGXClient> GXClient1; 
// Create Media Component 
HRESULT hr = ::CoCreateInstance(__uuidof(GXClient), 0, CLSCTX_INPROC_SERVER, 
	__uuidof(IGXClient), (void**) GXClient1); 

///////////////////////////////////////////////////////////// 
// Establish a connection between source and sink.
// m_dwCookie is a cookie identifying the connection, and is needed 
// to terminate the connection.
LPUNKNOWN pUnk = GetIDispatch(FALSE); 
if (!AfxConnectionAdvise(GXClient1, __uuidof(IGXClientEvents), pUnk, FALSE, &m_dwCookie))
{ 
  // Error.
    MessageBox("AfxConnectionAdvise Failed", "Gurux Media Sample", MB_OK | MB_ICONSTOP); 
    return FALSE;
}

Selecting media

First, select media, and then, set media settings.

//Select new Media
hr = GXClient1->SelectMedia("Net");
hr = GXClient1->GetCurrentMedia(&GXNet1);
//Set server port and TCP/IP address
GXNet1->put_HostName(L"Localhost");
GXNet1->put_HostPort(1234);
//Assign new Media
hr = GXClient1->AssignMedia(GXClient1);

Changing properties

Next, set Protocol properties. You can either select appropriate settings in Properties dialog, or set the settings programmatically, as follows:

//Set Protocol settings.
hr = GXClient1->put_HeaderSize(0);
//Make Error check
hr = GXClient1->put_DataSize(0);
//Make Error check 
hr = GXClient1->SetBOP("01", GX_VT_BYTE);
//Make Error check 
hr = GXClient1->SetEOP("02", GX_VT_BYTE);
//Make Error check
//OR
hr = GXClient1->Properties();
//Make Error check

Sending and receiving packets

Data can be sent synchronously or asynchronously. If data is sent synchronously, the sent packet is filled with the content of the received packet. If data is sent asynchronously, the response is received through GuruxClient ReceivedEventHandler.

Receiving event messages

To receive event messages, a notify interface must be created. Add following code to the header file, where notify interface is implemented.

//Add support for GXMedia component notifies
DECLARE_DISPATCH_MAP()
DECLARE_INTERFACE_MAP()

Add following code to the .cpp file, where notify interface is implemented.

//Add support for GXMedia component notifies
BEGIN_INTERFACE_MAP(CGXComSampleDlg, CDialog)
    INTERFACE_PART(CGXComSampleDlg, __uuidof(IGXClientEvents), Dispatch)
END_INTERFACE_MAP()
BEGIN_DISPATCH_MAP(CGXComSampleDlg, CCmdTarget)
    DISP_FUNCTION_ID(CGXComSampleDlg, "Received", 5, OnReceived, VT_EMPTY, VTS_UNKNOWN VTS_BOOL)
    DISP_FUNCTION_ID(CGXComSampleDlg, "OnError", 7, OnError, VT_EMPTY, VTS_WBSTR) 
END_DISPATCH_MAP()

/////////////////////////////////////////////////////////////////////////////
// Handle received data
/////////////////////////////////////////////////////////////////////////////
HRESULT CGXComSampleDlg::OnReceived(VARIANT* Data, BSTR SenderInfo)
{
    // Get Data size
    long lSize = 0;
    if(FAILED(SafeArrayGetUBound(Data->parray, 1, &lSize)))
    {
        return S_OK;
    }
    CComVariant data;
    for (long pos = 0; pos < lSize; pos++)
    {
        if (FAILED(SafeArrayGetElement(Data->parray, &pos, &data)))
        {
            return S_OK;
        }
        m_dataReceived += data.bVal;
    }
    m_sender = SenderInfo;
    UpdateData(FALSE);
    return S_OK;
}

/////////////////////////////////////////////////////////////////////////////
// Show occurred error
/////////////////////////////////////////////////////////////////////////////
HRESULT CGXComSampleDlg::OnError(BSTR ErrorInfo)
{
    USES_CONVERSION;
    MessageBox(W2T(ErrorInfo), "Gurux Media Sample", MB_OK | MB_ICONERROR);
    return S_OK;
}

Error Handling

It's very important to consider error handling when sending and receiving data. The connection can drop down, or something else unexpected may happen. If something unwanted happens, Gurux Client returns an error. The following example shows how to handle errors in C++.

////////////////////////////////////////////////////////////////////////////////
// This method helps you to see in text form what error GXCom returned.
////////////////////////////////////////////////////////////////////////////////
CString GetGXError(IUnknown* pUnknown)
{
    CString errStr;
    if (pUnknown == NULL)
    {
        return errStr;
    }
    CComPtr<ISupportErrorInfo> pSupportErrorInfo = NULL;
    CComPtr<IErrorInfo> pErrorInfo = NULL;
    HRESULT hr = pUnknown->QueryInterface(IID_ISupportErrorInfo, (void**) &pSupportErrorInfo);
    if (FAILED(hr))
    {
        return errStr;
    }
    
    //If interface does not support error info, don't go further.
    if (FAILED(pSupportErrorInfo->InterfaceSupportsErrorInfo(IID_IUnknown)))
    {
        return errStr;
    }
    
    // Get the current error object. Return if no error object exists.
    GetErrorInfo(0,&pErrorInfo);
    if (pErrorInfo == NULL) 
    {
        return errStr;
    }
            
    //Get error description
    CComBSTR err;
    pErrorInfo->GetDescription(&err);
    errStr = err;
    return errStr;
}

//////////////////////////////////////////////////////////////////////////////// 
// Create Media Components
////////////////////////////////////////////////////////////////////////////////
void CreateComponents()
{
    if(FAILED(::CoCreateInstance(__uuidof(GXClient), 0,
            CLSCTX_INPROC_SERVER,
            __uuidof(IGXClient),
            (void**) &m_GXClient1)))
    {
        //Show Error if any
        MessageBox(GetGXError(m_GXClient1), "Gurux Media Sample", MB_OK | MB_ICONERROR);
    }

    ///////////////////////////////////////////////////////////// 
    //Establish connection between source and sink. 
    //m_dwCookie is a cookie identifying the connection, and is needed 
    //to terminate the connection. 
    LPUNKNOWN pUnk = GetIDispatch(FALSE); 
    if (!AfxConnectionAdvise(m_GXClient1, __uuidof(IGXClientEvents), pUnk, FALSE, &m_dwCookie)) 
    {
        // Error. MessageBox("AfxConnectionAdvise Failed", "Gurux Media Sample", MB_OK | MB_ICONSTOP);
        return FALSE; 
    }
}

//////////////////////////////////////////////////////////////////////////////// 
// Close Media Components
////////////////////////////////////////////////////////////////////////////////
void CloseComponents()
{
    LPUNKNOWN pUnk = GetIDispatch(FALSE); 
    /////////////////////////////////////////////////////////////
    //Release sink. 
    //Terminate connection between source and sink. 
    //m_pUnkSrc is IUnknown of server obtained by CoCreateInstance(). 
    //m_dwCookie is a value obtained through AfxConnectionAdvise(). 
    if (!AfxConnectionUnadvise(m_GXClient1 , __uuidof(IGXClientEvents), pUnk, FALSE, m_dwCookie)) 
    {
        // Error. 
        MessageBox("AfxConnectionAdvise Failed", "CPP Sample", MB_OK | MB_ICONSTOP); 
    } 
            
    //Release Components when application is closing. 
    m_GXClient1 = NULL; 
    CoUninitialize(); 
}

Using the components from development environment

Using from .NET | Using from Visual Basic | Using from C++ | Parameter Types