Tutorial: RCC

The scope of this tutorial is to learn, how to create a source module which uses the RCC Api.

We will make use of the json_api framework, which allows us to encapsulate our code in a seperate source file, with well defined interfaces to the rest of the App.
The tutorial is based on a newly created innovaphone App with the Visual Studio plugin.

Basic ideas

The messages related to the RCC Api are identified by a property "api" having the value "RCC". The json_api within the AppWebsocket library is used to route all messages with this property to the code, which registered to handle this Api.

There may be multiple PBXs, from which a AppWebsocket connection is established, which provides this Api, so one object is used to keep a list of all these connections an other global information.

For each AppWebsocket connection another object is used to keep the status information

Step by step

The used file and class names in this example are based on a newly created App with the name NewApp1 and the company name innovaphone.

Your filenames might be different according to your settings.

Define the data structures in a new header file rccapi.h

Add new file rccapi.h to the NewApp1 folder

Place the following code in the header file

/*-----------------------------------------------------------------------------------------------*/
/* rccapi.h                                                                                      */
/* copyright (c) innovaphone 2019                                                                */
/*                                                                                               */
/*-----------------------------------------------------------------------------------------------*/
class RccApiSession;
class RccApi {
    class istd::list<RccApiSession> sessions;
public:
    RccApi();
    class JsonApi * CreateJsonApi(class IJsonApiConnection * connection, class json_io & msg, word base);
};

class RccApiSession : public JsonApi, public istd::listElement<RccApiSession> {
    const char * Name() { return "RCC"; };
    void Message(class json_io & msg, word base, const char * mt, const char * src);
    void JsonApiConnectionClosed();
    class RccApi * rccapi;
    class IJsonApiConnection * connection;

public:
    RccApiSession(class RccApi * rccapi, class IJsonApiConnection * connection);
    ~RccApiSession();

};

The class RccApi is used to keep a list of all current sessions and provides the public function CreateJsonApi to add a new AppWebsocket connection.
The class RccApiSession is created for each AppWebsocket connection from a PBX providing this Api

Add sceleton implementations to the functions of the new classes

Add the new file rccapi.cpp to the NewApp1 folder

Add includes for the required header files

/*-----------------------------------------------------------------------------------------------*/
/* rccapi.cpp                                                                                    */
/* copyright (c) innovaphone 2019                                                                */
/*                                                                                               */
/*-----------------------------------------------------------------------------------------------*/

#include "platform/platform.h"
#include "common/ilib/json.h"
#include "common/interface/json_api.h"
#include "rccapi.h"

Add define for debug outputs, so debugs can be removed from released code
```
#define DBG(x) debug->printf x
```

Add the code for RccApi class. The constructor and the CreateJsonApi function.

/*-----------------------------------------------------------------------------------------------*/
/* RccApi                                                                                        */
/*-----------------------------------------------------------------------------------------------*/

RccApi::RccApi()
{

}

class JsonApi * RccApi::CreateJsonApi(class IJsonApiConnection * connection, class json_io & msg, word base)
{
    DBG(("RccApi::CreateJsonApi()"));
    class RccApiSession * session = new RccApiSession(this, connection);
    sessions.push_back(session);
    return session;
}

Add the code for the RccApiSession class, which is created for each AppWebsocket connection

/*-----------------------------------------------------------------------------------------------*/
/* RccApiSession                                                                                 */
/*-----------------------------------------------------------------------------------------------*/

RccApiSession::RccApiSession(class RccApi * rccapi, class IJsonApiConnection * connection)
{
    DBG(("RccApiSession::RccApiSession()"));
    this->rccapi = rccapi;
    this->connection = connection;
    char sb[1000];
    class json_io send(sb);
    word base = send.add_object(0xffff, 0);
    send.add_string(base, "mt", "Initialize");
    send.add_string(base, "api", "RCC");

    connection->JsonApiMessage(send, sb);
    connection->RegisterJsonApi(this);
}

RccApiSession::~RccApiSession()
{
    DBG(("RccApiSession::~RccApiSession()"));
    connection->UnRegisterJsonApi(this);
}

void RccApiSession::Message(class json_io & msg, word base, const char * mt, const char * src)
{
    connection->JsonApiMessageComplete();

    DBG(("RccApiSession::Message(%s)", mt));
    if (!strcmp(mt, "UserInfo")) {
    }
}

void RccApiSession::JsonApiConnectionClosed()
{
    delete this;
}

Add the new files to the makefile

In NewApp1.mak add the following rule

APP_OBJS += $(OUTDIR)/obj/rccapi.o
$(OUTDIR)/obj/rccapi.o: NewApp1/rccapi.cpp

At this point the project should run a build without an error. You should check this.

Integrate the new code in NewApp1

In NewApp1.h add a rccapi pointer to the NewApp1 class for the created RccApi object
```
class RccApi * rccapi;
```
Include the new header file in NewApp1.cpp
```
#include "rccapi.h"
```
In the NewApp1 contructor the class RccApi should be created
```
rccapi = new RccApi();
```
In the NewApp1 destructor the class RccApi should be deleted
```
delete rccapi;
```

When a PbxInfo message is received a call to CreateJsonApi is used to make use of this connection for the RCC Api

else if (!strcmp(mt, "PbxInfo")) {
    badgecount = new BadgeCountSignaling(instance, this);
    instance->rccapi->CreateJsonApi(this, msg, base); // new line
    AppWebsocketMessageComplete();
}

Run the new code

Run the App and check in the log file what is happening.