Tutorial 1: The basics

This is the first of a string of articles intended to teach you how to write your first CopperLan application.

Prerequisites

It is of course necessary to have the latest version of CopperLan installed on your computer. You need to go to the Copperlan website, make an account and download the SDK.

Goal

The goal of this first lesson is to write a console application that declares a device on the CopperLan network. It fits well with the global intent of the tutorial which about a black-box type of application, lacking direct interaction with the user, that allows to apply changes to a CopperLan message flow. The idea is to have access to small applications that can run in any machine on the network, are remote editable, and can, for example, be inserted between a keyboard and a sound generator to apply effects such as delay, transpose, arpeggiator, ...

Engine Class

As its name implies, this class is the engine of the application. It should be instantiated in the main() and its Initialize() method be called for the application to run. A call to Terminate allows to quit in a clean way. Here is the main body of the program:

#include "Engine.h"
Engine g_Engine;

int main(int argc, char* argv[]) {
    //Initialisation
    if (g_Engine.Initialize())
    {
        printf("Program running... Press any key to exit\n");
        getchar();
        // Terminaison
        g_Engine.Terminate();
    }
    else
        printf("aborting...\n");
}

We will now define the prototype of the Engine class, and thus make use of CopperLan resources. Given that our example is based on the freeware SDK, it is needed to do the following include and ensure that the path to that file is defined globally for the whole project, or in the default parameters of your development environment.

#include <stdio.h>
#include "CHAI.h"

class Engine
{
public:
    //====================
    // Constructor/Destructor
    //====================
    Engine();
    ~Engine();
    //====================
    // Public methods
    //====================
    bool Initialize();
    void Terminate();
private:
    //====================
    // Members
    //====================
    CPNS::ICHAI* m_pCHAI;
    CPNS::IBaseLocalDevice* m_pDevice;
    CPNS::IInput* m_pInput;
    CPNS::IOutput* m_pOutput;
};

The implementation of the constructor/destructor is usual:

Engine::Engine() :
m_pCHAI(NULL),
m_pDevice(NULL),
m_pInput(NULL),
m_pOutput(NULL)
{
}

Engine::~Engine()
{
}

The Initialize() method creates one instance of the CHAI, one Device, one Input and one Output.

bool Engine::Initialize()
{

    // Creation of one instance of the CHAI; the freeware key provides its identity.
    // The key contains the identity of the freeware and the name of the application
    // You can get a new key for your freeware at no cost and on simple request.
    m_pCHAI = CPNS::Factory::CreateCHAI("@7ZSwec9Pk@Yg5vjw1hQekXiuih8wWn2&3&@");

    // Addition of a generic device.
    // This device is declared as being in the Performance device category,
    // which means that it is used for musical performance.
    // Beware: the pointer returned is relating to an object maintained by the CHAI
    // (it derives from IObject). It is forbidden to try deleting such object.
    // Device deletion is done through the CHAI's RemoveLocalDevice method.

    m_pDevice = m_pCHAI->AddLocalDevice(34,
                                        423,
                                        CPNS::Enums::DuplicateModes::DM_Auto,
                                        false,
                                        CPNS::Enums::ExtendedDeviceCapabilities::EDC_Any,
                                        "MyPlugIn");

    if (!m_pDevice) return false;


    // Addition of an Input to the device.
    // The parameters are:
    // 1) a combination of the Input capabilities, here able to receive Event,
    // Modifier, and Selector messages.
    // 2) the name of the input

    m_pInput = m_pDevice->AddInput(
                                   CPNS::Enums::IOC_Msg_Event |
                                   CPNS::Enums::IOC_Msg_Modifier |
                                   CPNS::Enums::IOC_Msg_Selector,
                                    "Input",
                                   CPNS::SectionID::AnyInstanceOf(CPNS::Enums::SECT_Other)
                                  );

    if (!m_pInput) return false;


    // Addition of an Output to the Device.
    // The parameters are:
    // 1) a combination of the Output capabilities, here able to emit Event,
    // Modifier, and Selector messages
    // 2) the name of the output

    m_pOutput = m_pDevice->AddOutput(
                                     CPNS::Enums::IOC_Msg_Modifier |
                                     CPNS::Enums::IOC_Msg_Event |
                                     CPNS::Enums::IOC_Msg_Selector,
                                     "Output",
                                     CPNS::SectionID::AnyInstanceOf(CPNS::Enums::SECT_Other));

    if (!m_pOutput) return false;

    // A ce stade, le Device n'est pas encore visible sur le réseau CopperLan.
    // Lors de la connexion du CHAI, un test est réalisé pour vérifier si il n'y a pas un
    // conflit d'identité. Ceci peut arriver si on exécute plusieurs fois le même
    // programme en même temps. Dans ce cas, CopperLan attribue automatiquement
    // un nouveau DuplicateNumber afin de résoudre le conflit.

    // At this stage, the Device is not visible yet on the CopperLan network.
    // During the CHAI connection, a test is effected to ensure that there is no identity conflict.
    // This can happen if the same program is run more than once at the same time.
    // In such case, CopperLan will automatically allocate a new DuplicateNumber in order
    // to solve the conflict.

    bool fConnected = (m_pCHAI->Connect() == CPNS::Enums::ERR_None);

    return fConnected;
}

The ending of the application simply consists in freeing the resources used.

void Engine::Terminate()
{
    // CHAI disconnection
    m_pCHAI->Disconnect();
    // Destruction of the CHAI and all associated resources
    m_pCHAI->Destroy();
    m_pCHAI = NULL;
    m_pDevice = NULL;
    m_pInput = NULL;
    m_pOutput = NULL;
}

That's it; you now have an application that declares a Device, an Input, and an Output on the network. At this stage, it is possible to send it messages and add it destinations. Keep in mind that nothing will happen yet, given that we don't handle the incoming messages and we don't send any!

Source from http://copperlan.blogspot.be/2010/10/tutorial-1-basics.html, updated 15/07/2015 on MacOSX 10.10