Skip to content

Usage

object: rpc (Remote Procedure Call)

rpc object exposes trust-safe properties, functions and events to provide reliable two-way messaging (request-response) between multiple endpoints allowing you to build sophisticated asynchronous interactions.

Concepts

  • RPC endpoint / server (CALLEE)
  • Application using dataBridges server library can expose callback function(s) as a dataBridges rpc function.
  • Multiple callback function(s), can be exposed as rpc functions grouped together as an rpc endpoint / server.
  • To deploy access-controlled, trust-safe rpc endpoint / server, prefix the rpc server namespace with pvt: or prs:
    • Note dataBridges have 2 separate libraries (client lib, server lib). You are reading the server library api document.
    • Server lib uses app.key along with secret to get access to rpc endpoint/server including pvt: , prs: access controlled rpc endpoint/server.
    • Whereas application using client library (client application) will always need to pass a trust-token to access restricted rpc endpoint/server (prefixed with pvt: prs:) . A trust-token is a JWT document created using a combination of channelname + sessionid + app.secret. Trust token can be created by application having access to app.key's secret.
      • you can use your existing access control, authorization and session identification rule-set, process and methods to create a trust-token instructing the dataBridges router to accept the pvt: prs: rpc call() client application.
      • Trust-tokens allows you to enable secured, access controlled and compliance driven two-way messaging (request-response) between multiple endpoints allowing you to build sophisticated asynchronous interactions in your existing and new initiative applications.
  • RPC clients (CALLER)
  • Both dataBridges client and server api's allow you to execute rpc function(s) exposed by rpc endpoint / server.
  • Application consuming rpc function(s) is called CALLEE and the rpc endpoint/server application is called CALLER.
  • CALLEE application will execute a remote function by passing IN.paramter, and a timeout
    • The CALLER application's corresponding function will be invoked with the IN.parameter and it will respond with response() or exception() which will be delivered back to the CALLEE application by dataBridges network completing the request-response communication.
  • CALLEE application need not be aware about RPC servers (CALLER) identity and will only interact with RPC server (CALLER) namespace. The dataBridges network will intelligently route and load balance RPC call() to the RPC server application. The dataBridges network will automatically load balance multiple instance of server application exposing the same RPC endpoints.

To expose rpc functions the application needs to register an rpc server and register callback functions to rpc server as rpc functions.

  • The steps involved are :
  • Initialize rpc endpoint/server using init().
  • Register all rpc functions using regfn().
  • Register rpc endpoint/server with dataBridges network using register()

Initialize rpc Server

Initialize the server using rpc.init function of your dataBridges object. This will return an object to which all properties, functions and events are available.

Note : Application can have multiple rpc endpoint/server against a dataBridges object.

//lets create an rpc endpoint/server named missionControl and expose 2 functions called nasa and isro.

try {
    const missionControl = dbridge.rpc.init('missionControl');
} catch (err) {
    console.log(err.source, err.code, err.message);
}
# lets create an rpc endpoint/server named missionControl and expose 2 functions called nasa and isro.
try:
     missionControl = dbridge.rpc.init('missionControl')
except dBError as e:
     print(e.code, e.source, e.message) 
//lets create an rpc endpoint/server named missionControl and expose 2 functions called nasa and isro.
using dBridges.remoteprocedure; 

try {
    Crpcserver missionControl = dbridge.rpc.init('missionControl');
} catch (dBError err) {
    Console.WriteLine("{0} ,  {1} , {2}" , err.source, err.code, err.message);
}
Parameter Rules Description
string serverName **OR*
pvt:**serverName **OR
**prs:**serverName*
Initialize a rpcServer with *server*Name .
Return Type Description
object rpcObject which events, properties and related functions can be bound to.
Exceptions:
Source Code Description
DBLIB_RPC_INIT INVALID_SERVERNAME Applicable for below conditions
1. serverName is not defined.
2. serverName already exists
3. serverName is blank.
4. serverName validation error, length of serverName greater than 64
5. serverName validation error, serverName fails a-zA-Z0-9\.:_- validation.
6. serverName contains : and first token is not pvt,prs.

Register rpc functions

Application can expose callback function(s) as rpc functions. Application using dataBridges client/server library can remotely execute the rpc functions. Each function needs to be registered with the library as a rpc function, using rpc.regfn()where you can link the functionName to rpcFunctionName.

  • The server application that exposes the rpc function is called a CALLEE.
  • The client/server application that executes the rpc function is called a CALLER.

Functions can be defined either inside the property callback function or anywhere in the scope of application. Below code exhibits both ways of exposing the function.

// function is exposed outside the property callback function, but in the scope of application.
function rpcFuncOustide (payload, response) {
    try {
        response.tracker = true;
        response.next('This is Houston');
        response.end('message received by Houston');
        response.exception('INVALID_PARAM', 'Wrong parameter'); 
    } catch(err) {
        console.log(err.source, err.code, err.message);
    }
}

missionControl.functions = function () {
    // function is exposed inside the property callback function.
    function rpcFuncInside (payload, response) {
        try {
            response.tracker = true;
            response.next('This is Hassan');
            response.end('message received by Hassan');
            response.exception('INVALID_PARAM', 'Wrong parameter'); 
            console.log(response.id);
        } catch(err) {
            console.log(err.source, err.code, err.message);
        }
    }
    // registering function to be exposed by rpcServer
    try {
        missionControl.regfn("nasa", rpcFuncOustide);
        missionControl.regfn("isro", rpcFuncInside);
    } catch(err) {
        console.log(err.source, err.code, err.message);
    }
}

// unregistering of function exposed by rpcServer
missionControl.unregfn("nasa", rpcFuncOustide);
# function is exposed outside the property callback function, but in the scope of application.
async def rpcFunOutside(inparameter, response):
  try:
    response.tracker = True
    print("iparameter = " , inparameter.inparama)
    print("extra info  = " , inparameter.sysinfo)
    response.next('This is Houston')
    response.end('message received by Houston')
    response.exception('INVALID_PARAM', 'Wrong parameter') 
except dBError as e:
    print(e.code, e.source, e.message) 

# function is exposed inside the property callback function.
async def rpcFunctionBinder():
    # function is exposed inside the property callback function, but in the scope of application.
    async def rpcFunInside(inparameter, response):
        response.tracker = True
        try:
          response.tracker = True
          print("iparameter = " , inparameter.inparama)
          print("extra info  = " , inparameter.sysinfo)
          response.next('This is Hassan')
          response.end('message received by Hassan')
          response.exception('INVALID_PARAM', 'Wrong parameter') 
        except dBError as e:
          print(e.code, e.source, e.message) 

   try:
      #// registering function to be exposed by rpcServer
      missionControl.regfn("nasa", rpcFunInside)
      missionControl.regfn("isro", rpcFunOutside)
   except dBError as e:
      print(e.code, e.source, e.message) 

missionControl.functions = rpcFunctionBinder
# unbinding of function exposed by rpc functions
missionControl.unregfn("rpcFunOutside", ifunctionoutside)
// function is exposed outside the property callback function, but in the scope of application.
using dBridges.responseHandler;
using dBridges.Utils;
async void rpcProcOutside(object inparam, object response)
{
    try {
        dBParams parameter = inparam as dBridges.Utils.dBParams;
        Console.WriteLine("iparameter = {0}" , parameter.inparama);
        Console.WriteLine("extra info  = {0}" , parameter.sysinfo);

        CResponseHandler responsehandler = response as CResponseHandler;
        responsehandler.tracker = true;
        responsehandler.next('This is Houston');
        responsehandler.end('message received by Houston');
        responsehandler.exception('INVALID_PARAM', 'Wrong parameter'); 
    } catch (dBError err) {
        Console.WriteLine("{0} ,  {1} , {2}" , err.source, err.code, err.message);
    }
}

// function is exposed inside the property callback function.
async void RpcFunctionBinder(object sender)
{
    try{
        //sender is same as rpcSvrObject 
        // function is exposed outside the property callback function, but in the scope of application.
       Action<object , object> ifunctionoutside = rpcProcOutside;

        // registering function to be exposed by rpcServer
       missionControl.regfn("nasa", ifunctionoutside);

        // registering function to be exposed by rpcServer
        Action<object , object> ifunctioninside;
        missionControl.regfn("isro", ifunctioninside = (object inparam, object response) =>{
        // function is exposed inside the property callback function, but in the scope of application.
             try {
                dBParams parameter = inparam as dBridges.Utils.dBParams;
                Console.WriteLine("iparameter = {0}" , parameter.inparama);
                Console.WriteLine("extra info  = {0}" , parameter.sysinfo);

                CResponseHandler responsehandler = response as CResponseHandler;
                responsehandler.tracker = true;
                responsehandler.next('This is Houston');
                responsehandler.end('message received by Houston');
                responsehandler.exception('INVALID_PARAM', 'Wrong parameter'); 
            } catch (dBError err) {
            Console.WriteLine("{0} ,  {1} , {2}" , err.source, err.code, err.message);
            }       
        });

    } catch (dBError err) {
        Console.WriteLine("{0} ,  {1} , {2}" , err.source, err.code, err.message);
    }
}

Action<object> irpcFunctions = RpcFunctionBinder;
missionControl.functions = irpcFunctions; 

// unregistering of function exposed by rpcServer
missionControl.unregfn("rpcProcOutside", ifunctionoutside);

Below are parameters of the callback function which is exposed to rpcServer.

Parameter Description
payload (object) Input payload from the caller.
response (object) Response object having properties and function to return execution results of the function back to caller.
payload: (object)
Properties/Function Description
inparam (string) Input parameters received to execute the function.
sessionid (string) Session id of the member who has requested to execute the function.
libtype (string) Library Lang of the member who has requested to execute the function.
sourceipv4 (string) IPv4 of the member who has who has requested to execute the function.
sourceipv6 (string) IPv6 of the member who has who has requested to execute the function.
info (string) System Info of the member who has who has requested to execute the function.
response: (object)
Properties/Function Description
tracker (boolean) This will enable response tracker, and event rpc.response.tracker will be fired if any issue happens in sending back response to caller. Enable this property if your function needs a confirmation of response delivered to the caller.
id (string) (readonly) Each rpc function execution is assigned a unique ID by the library. when the response tracker is enabled, the application can bind to an event rpc.response.tracker to get the delivery notification. The event will indicate the delivery notification linked to this ID. Caller application will need to maintain this ID to track the delivery notification.
next (function) dataBridges rpc supports multi-part response. Application can use response.next to send multi-part response to the caller.
end (function) response.end is to send the final response to the caller. Once end is called, the object is closed and no more response can be sent.
exception (function) Two parameter, return errorCode (string) ,errorMessage (string) is sent to caller. This will raise an exception at the caller library.
Exceptions:

Below exceptions are raised in the rpc.regfn.

Source Code Description
DBLIB_RPC_REGFN INVALID_FUNCTION_NAME Invalid Function name.
DBLIB_RPC_REGFN INVALID_CALLBACK Callback is not a function or is not defined.

Below exceptions are raised on response object inside the registered function.

Source Code Description
DBNET_RPC_CALL NETWORK_DISCONNECTED Connection to dataBridges network is not active.
DBLIB_RPC_CALL RESPONSE_OBJECT_CLOSED Return response object is closed. Thus the function is unable to respond back to the call.

Register Server

Register rpc endpoint/server with dataBridges network using register().

try {
    missionControl.register();
} catch (err) {
    console.log(err.source, err.code, err.message);
}

// Best practice is to check the channel is online before publishing any message.
if (dbridge.connectionstate.isconnected()) {
    try {
        missionControl.register();
    } catch (err) {
        console.log(err.source, err.code, err.message);
    }
}
try:
    missionControl.register()
except dBError as e:
    print(e.code, e.source, e.message)

# Best practice is to check the channel is online before publishing any message.
if dbridge.connectionstate.isconnected():
    try:
        missionControl.register()
    except dBError as e:
        print(e.code, e.source, e.message)
try {
    missionControl.register();
} catch (dBError err) {
    Console.WriteLine("{0} ,  {1} , {2}" , err.source, err.code, err.message);
}

// Best practice is to check the channel is online before publishing any message.
if (dbridge.connectionstate.isconnected()) {
    try {
        missionControl.register();
    } catch (dBError err) {
        Console.WriteLine("{0} ,  {1} , {2}" , err.source, err.code, err.message);
    }    
}
Exceptions:
Source Code Description
DBLIB_RPC_REGISTER RPC_INVALID_FUNCTIONS Applicable for below conditions
1. If "callback function" is not declared for rpc server
2. typeof() variable defined is not a "function".
DBLIB_RPC_REGISTER NETWORK_DISCONNECTED Connection to dataBridges network is not active.

Unregister Server

rpcServer can be unregistered from dataBridges server library using unregister function of your rpcServerObject.

missionControl.unregister();
missionControl.unregister()
missionControl.unregister();

resetqueue()

dbridgeObject The dataBridges network maintains in-process rpc function execution status. resetqueue() informs the dataBridges network that all in-process rpc function execution will be dropped by the application and response to be invalidated. Resetqueue() use case is intended to be used by application in its self health status management. Sometime due to the application process flow, the application can identify situation where it would like to ease its load by resettiing the rpc function execution queue by sending resetqueue() message to dataBridges network and than closing all in-process rpc function execution.

try {
    missionControl.resetqueue();
} catch(err) {
    console.log(err.source, err.code, err.message);
}
try:
    await missionControl.resetqueue();
except dBError as e:
    print(e.code, e.source, e.message)
try {
    missionControl.resetqueue();
} catch (dBError err) {
    Console.WriteLine("{0} ,  {1} , {2}" , err.source, err.code, err.message);
}
Exceptions:
Source Code Description
DBLIB_RPC_CALL NETWORK_DISCONNECTED Connection to dataBridges network is not active.

System events for rpc server registration.

There are a number of events which are triggered internally by the library, but can also be of use elsewhere. Below are the list of all events triggered by the library.

Below syntax is same for all system events.

//  Binding to systemevents on rpcObject  
try {
    missionControl.bind('eventName',  (payload, metadata) => {
        console.log(payload, metadata);
    });
} catch(err){
     console.log(err.source, err.code, err.message);
}

// Binding to systemevents on dbridgeObject 
try {
    dbridge.rpc.bind('eventName', (payload, metadata) => {
        console.log(payload, metadata);
    });
} catch(err){
     console.log(err.source, err.code, err.message);
}
#  Binding to systemevents on rpcObject  
async def eventCallback(payload , metadata):
    print(payload , metadata)
try:
    rpcSvrObject.bind('eventName', eventCallback)
except dBError as e:
    print(e.code, e.source, e.message) 

# Binding to systemevents on dbridgeObject 
try:
    dbridge.rpc.bind('eventName',  eventCallback)
except dBError as e:
    print(e.code, e.source, e.message)
//  Binding to systemevents on rpcObject  
try {
    Action<object , object> ievent;
    rpcSvrObject.bind("eventName", ievent = (object inparam, object metadata) =>{
        Console.WriteLine("{0} ,  {1}" , inparam ,  metadata);
    });
} catch (dBError err) {
    Console.WriteLine("{0} ,  {1} , {2}" , err.source, err.code, err.message);
}

// Binding to systemevents on dbridgeObject 
try {
    Action<object , object> ievent;
    dbridge.rpc.bind("eventName",  ievent = (object inparam, object metadata) =>{
        Console.WriteLine("{0} ,  {1}" , inparam ,  metadata);
    });
} catch (dBError err) {
    Console.WriteLine("{0} ,  {1} , {2}" , err.source, err.code, err.message);
}

Callback out parameter payload, metadata details are explained with each event below in this document.

Exceptions:
Source Code Description
DBLIB_RPC_BIND INVALID_EVENTNAME Invalid Event name. Not in default events.
DBLIB_RPC_BIND INVALID_CALLBACK Callback is not a function or is not defined.

bind_all and unbind_all

bind_all and unbind_all work much like bind and unbind, but instead of only firing callbacks on a specific event, they fire callbacks on any event, and provide that event in the metadata to the handler along with the payload.

//  Binding to all rpc events on rpcObject  
try {
    rpcObject.bind_all((payload, metadata) => {
        console.log(payload, metadata);
    });
} catch(err){
     console.log(err.source, err.code, err.message);
}

// Binding to all rpc events on dbridgeObject 
try {
    dbridge.rpc.bind_all((payload, metadata) => {
        console.log(payload, metadata);
    });
} catch(err){
     console.log(err.source, err.code, err.message);
}
# Binding to rpc events on rpcObject  
def eventFunction(payload ,  metadata):
  print(payload , metadata)

try:
    rpcObject.bind_all('event',  eventFunction)
except dBError as e:
  print(e.code, e.source, e.message) 

# Binding to rpc events on dbridgeObject 
try {
    dbridge.rpc.bind_all('event', eventFunction)
except dBError as e:
  print(e.code, e.source, e.message) 
//  Binding to all rpc events on rpcObject  
try {
    Action<object , object> irpcstatus;
    rpcObject.bind_all(irpcstatus =  (payload, metadata) => {
        Console.WriteLine("{0} , {1} " , payload, metadata);
    });
} catch (dBError err) {
    Console.WriteLine("{0} ,  {1} , {2}" , err.source, err.code, err.message);
}

// Binding to all rpc events on dbridgeObject 

try {
    Action<object , object> irpcstatus;
    dbridge.rpc.bind_all(irpcstatus =  (payload, metadata) => {
        Console.WriteLine("{0} , {1} " , payload, metadata);
    });
} catch (dBError err) {
    Console.WriteLine("{0} ,  {1} , {2}" , err.source, err.code, err.message);
}

Callback out parameter payload, metadata details are explained with each event below in this document.

Exceptions:
Source Code Description
DBLIB_CONNECT_BIND INVALID_CALLBACK If "callback function" is not declared or typeof() variable defined is not a "function".

unbind_all works similarly to unbind.

// Remove just `handler` across the rpc server 
rpcObject.unbind_all(handler);

//Remove all handlers for the all event in the subscribed/connected rpc server
rpcObject.unbind_all();

// Remove `handler` across the subscribed/connected rpc servers
dbridge.rpc.unbind_all(handler);

// Remove all handlers for all events across all subscribed/connected rpc servers
dbridge.rpc.unbind_all();
# Remove just `handler` across the rpc server 
rpcObject.unbind_all(handler)

# Remove all handlers for the all event in the subscribed/connected rpc server
rpcObject.unbind_all()

# Remove `handler` across the subscribed/connected rpc servers
dbridge.rpc.unbind_all(handler)

# Remove all handlers for all events across all subscribed/connected rpc servers
dbridge.rpc.unbind_all()
// Remove just `handler` across the rpc server 
rpcObject.unbind_all(handler);

//Remove all handlers for the all event in the subscribed/connected rpc server
rpcObject.unbind_all();

// Remove `handler` across the subscribed/connected rpc servers
dbridge.rpc.unbind_all(handler);

// Remove all handlers for all events across all subscribed/connected rpc servers
dbridge.rpc.unbind_all();

dbridges:rpc.server.registration.success

Callback parameters
payload:

null

metadata (dict):
{
    "servername": "serverName" ,                        // (string) serverName to which connection is done.
    "eventname": "dbridges:rpc.server.registration.success", // (string) eventName 
}

dbridges:rpc.server.registration.fail

Callback parameters
payload: (dberror object)
{
    "source": "DBNET_RPC_REGISTER" ,        // (string) Error source
    "code": "ERR_ACCESS_DENIED",            // (string) Error code 
    "message": ""                           // (string) Error message if applicable.
}
metadata (dict):
{
    "servername": "serverName" ,                    // (string) serverName to which connection is done.
    "eventname": "dbridges:rpc.server.registration.fail",// (string) eventName 
}

dbridges:rpc.server.unregistration.success

Callback parameters
payload:

null

metadata (dict):
{
    "servername": "serverName" ,            // (string) serverName to which connection is done.
    "eventname": "dbridges:rpc.server.unregistration.success", // (string) eventName 
}

dbridges:rpc.server.unregistration.fail

Callback parameters
payload: (dberror object)
{
    "source": "DBNET_RPC_REGISTER" ,    // (string) Error source
    "code": "ERR_ACCESS_DENIED",      // (string) Error code 
    "message": ""               // (string) Error message if applicable.
}
metadata (dict):
{
    "servername": "serverName" ,          // (string) serverName to which connection is done.
    "eventname": "dbridges:rpc.server.registration.fail",// (string) eventName 
}

dbridges:rpc.server.online

Callback parameters
payload:

null

metadata (dict):
{
    "servername": "serverName" ,           // (string) serverName to which connection is done.
    "eventname": "dbridges:rpc.server.online", // (string) eventName 
}

dbridges:rpc.server.offline

Callback parameters
payload:

null

metadata (dict):
{
    "servername": "serverName" ,                    // (string) serverName to which connection is done.
    "eventname": "dbridges:rpc.server.offline",// (string) eventName 
}

dbridges:rpc.response.tracker

Only available with rpcObject.

Callback parameters
Return Values Description
payload (string) Tracker identifier. which is same as response.id
metadata (string) Refer below table
Error Identifier Description
RE_18326 rpc caller is disconnected from dataBridges network and hence cannot process response tracking.
RE_19219 rpc caller is disconnected from dataBridges network and hence cannot process response tracking.
RE_22184 rpc caller is disconnected from dataBridges network and hence cannot process response tracking.
RE_22454 The cf callee is disconnected from dataBridges network
RE_23101 The cf callee is disconnected from dataBridges network
RE_29623 The cf callee is disconnected from dataBridges network
RE_29753 The cf callee is disconnected from dataBridges network

dbridges:rpc.callee.queue.exceeded

Only available with rpcObject.

Callback parameters
payload: (dberror object)
{
    "source": "DBNET_RPC_CALL" ,            // (string) Error source
    "code": "ERR_CALLEE_QUEUE_EXCEEDED",    // (string) Error code 
    "message": ""                           // (string) Error message if applicable.
}
metadata:

null

dberror:

Source Code Description
DBLIB_RPC_REGISTER NETWORK_DISCONNECTED Connection to dataBridges network is not active.
DBNET_RPC_REGISTER ERR_ACCESS_DENIED dataBridges network reported access violation with access_token function during current operation.
DBNET_RPC_REGISTER ERR_FAIL_ERROR dataBridges network encountered error during current operation.
DBNET_RPC_CALL ERR_CALLEE_QUEUE_EXCEEDED No new rpc calls are being routed by the dataBridges network to the application because the application's current rpc processing queue has already exceeded.
Each application connection cannot exceed rpc.queue.maximum. Refer to management console documentation for rpc.queue.maximum details.

Server Information

isOnline()

rpcObject provides a function to check if the channel is online.

const rpcServer_isonline = rpcObject.isOnline();
rpcServer_isonline = rpcObject.isOnline()
bool rpcServer_isonline = rpcObject.isOnline(); 
Parameter Rules Description
string serverName **OR*
pvt:**serverName **OR
**prs:**serverName*
*server*Name to which subscription to be done.
Return Values Description
boolean Is the current status of server connection online or offline.

getServerName()

rpcObject provides a function to get the serverName.

const rpcServerName = rpcObject.getServerName() 
rpcServerName = rpcObject.getServerName() 
string rpcServerName = rpcObject.getServerName() 
Return Type Description
string serverName of connected rpcServer.

Connect to Server

To use rpc functions, the application has to connect to the rpc endpoint/server. This is done using connect() function explained below.

connect()

The default method for connecting to a rpc endpoint/server involves invoking the rpc.connect function of your dataBridges object.

try {
    const rpcSvrClient = dbridge.rpc.connect('rpcServer'); 
    //name of the rpc endpoint/server that app wants to connect to. In our above example missionControl.
} catch (err) {
    console.log(err.source, err.code, err.message);
}
try:
     rpcSvrClient = dbridge.rpc.connect('rpcServer')
    # name of the rpc endpoint/server that app wants to connect to. In our above example missionControl.
except dBError as e:
     print(e.code, e.source, e.message) 
using  dBridges.remoteprocedure;
try {
    CrpCaller rpcSvrClient = dbridge.rpc.connect('rpcServer');
    //name of the rpc endpoint/server that app wants to connect to. In our above example missionControl.
} catch (dBError err) {
    Console.WriteLine("{0} ,  {1} , {2}" , err.source, err.code, err.message);
}
Parameter Rules Description
string serverName **OR*
pvt:**serverName **OR
**prs:**serverName*
*server*Name to which connection to be done.
Return Type Description
object rpcObject which events and related functions can be bound to.
Exceptions:
Source Code Message Description
DBLIB_RPC_CONNECT INVALID_SERVERNAME Applicable for below conditions
1. serverName is not defined.
2. serverName validation error, length of serverName greater than 64
3. serverName validation error, serverName fails a-zA-Z0-9\.:_- validation.
4. serverName contains : and first token is not pvt,prs.
DBLIB_RPC_CONNECT NETWORK_DISCONNECTED Connection to dataBridges network is not active.
DBNET_RPC_CONNECT ERR_FAIL_ERROR dataBridges network encountered error during current operation.
DBNET_RPC_CONNECT ERR_ACCESS_DENIED dataBridges network reported access violation with access_token function during current operation.

Execute Remote Procedure Call

call()

rpcObject call() function allows you to execute a remote function hosted by RPC endpoint / server using dataBridges library

  • passing function parameter as parameter
  • while setting an time to live (TTL) for the response

The RPC call() functions supports multi-part response (where the RPC function can send back multiple responses to a single RPC function call) along with exception routine.

rpcSvrClient.call(functionName, parameter, ttlms, (response) => {
    console.log('multipart response',response)
}).then((response) => {
    console.log('end response', response)
}).catch((err) => {
    console.log('exception',err.source, err.code, err.message);
});

//Below example how a application can connect to a RPC endpoint / Server called mathServer and use add, multiply functions.
try {
    const myMathServer = dbridge.rpc.connect('mathServer');
} catch (err) {
    console.log(err.source, err.code, err.message);
}

let obj = { "num1":44.5, "num2":30};
let inparam = JSON.stringify(obj);

myMathServer.call(add, inparam, ttlms, (response) => {
}).then((response) => {
    console.log('response: ', JSON.parse(response));
}).catch((err) => {
    console.log('exception',err.source, err.code, err.message);
});

myMathServer.call(multiply, inparam, ttlms, (response) => {
}).then((response) => {
    console.log('response: ', JSON.parse(response));
}).catch((err) => {
    console.log('exception',err.source, err.code, err.message);
});
def progress(response):
    print("multipart: " , response)

def onResult(response):
    print("response: ", response)

def onError(error):
    print(error.code, error.source, error.message)
try:
    p =  await rpcClient.call("functionName" ,  parameter , 10000, progress)
    p.then(onResult).catch(onError)
except dBError as e:
    print(e.code, e.source, e.message) 

# Below example how a application can connect to a RPC endpoint / Server called mathServer and use add, multiply functions.
try:
    myMathServer = dbridge.rpc.connect('mathServer');
except dBError as e:
    print(e.code, e.source, e.message) 

obj = { "num1":44.5, "num2":30};
inparam = json.dumps(obj);
try:
    p =  await myMathServer.call(add ,  inparam , 10000, progress)
    p.then(onResult).catch(onError)

    q =  await myMathServer.call(multiply ,  inparam , 10000, progress)
    q.then(onResult).catch(onError)
except dBError as e:
    print(e.code, e.source, e.message) 
Action<object> iprogress;
IPromise<object> p = rpcClient.call(functionName, parameter, ttlms, iprogress = (response) => {
    Console.WriteLine("multipart response {0}",response)
});
p.Then((response) => {
    Console.WriteLine("end response {0}", response)
}).Catch((err) => {
    Console.WriteLine("exception {0}", err);
});

//Below example how a application can connect to a RPC endpoint / Server called mathServer and use add, multiply functions.
try {
    CrpCaller myMathServer = dbridge.rpc.connect('mathServer');
}catch (dBError err) {
    Console.WriteLine("{0} ,  {1} , {2}" , err.source, err.code, err.message);
}

Dictionary<string , int> obj = new Dictionary<string,int32>() { {"num1",44.5} , {"num2",30} };
inparam = new JavaScriptSerializer().Serialize(obj);

Action<object> iprogress;
IPromise<object> p = myMathServer.call(add, inparam, ttlms, iprogress = (response) => {
    Console.WriteLine("multipart response {0}",response)
});
p.Then((response) => {
    Console.WriteLine("end response {0}", response)
}).Catch((err) => {
    Console.WriteLine("exception {0}", err);
});

Action<object> iprogress;
IPromise<object> p = myMathServer.call(multiply, inparam, ttlms, iprogress = (response) => {
    Console.WriteLine("multipart response {0}",response)
});
p.Then((response) => {
    Console.WriteLine("end response {0}", response)
}).Catch((err) => {
    Console.WriteLine("exception {0}", err);
});
Parameter Expected Value Description
functionName functionname (string) Function name as defined in rpc endpoint/ Server .
Note - RPC endpoint / server can expose multiple rpc functions.
parameter function parameter (string) if multiple parameters to be passed, This can be done by putting it into array or json and stringify the object.
ttlms 1000 (integer) Time to live in millisecond, timeout value before the call() function throws error timeout.
Return Values Description
string Multipart or final response. in case of error, dberror object is returned.
Exceptions:
Source Code Description
DBNET_RPC_CALL NETWORK_DISCONNECTED Connection to dataBridges network is not active.
DBNET_RPC_CALL RESPONSE_TIMEOUT Response not received from dataBridges network within defined ttlms. This may be due to dataBridges network or late response from rpcServer
DBLIB_RPC_CALL ID_GENERATION_FAILED Internal Library error.
DBNET_RPC_CALL ERR_ACCESS_DENIED dataBridges network reported access violation during current operation.
DBRPCCALLEE_RPC_CALL ERR_error_message This indicates an exception encountered by the remote RPC function. ERR_error_code will have the details.
DBNET_RPC_CALL CLE_NR_10865 rpc endpoint / server disconnected from dataBridges network. Try again.
DBNET_RPC_CALL CLE_NR_30391 rpc endpoint / server disconnected from dataBridges network. Try again.
DBNET_RPC_CALL CLE_QX_41074 Cannot process the call() because the RPC server (in this case CALLEE) has exceeded outstanding pending rpc call() queue limit.
DBNET_RPC_CALL CLE_QX_49467 Cannot process the call() because the RPC server (in this case CALLEE) has exceeded outstanding pending rpc call() queue limit.
DBNET_RPC_CALL CLR_QX_39305 Cannot process the call() because the RPC server (in this case CALLEE) has exceeded outstanding pending rpc call() queue limit.
DBNET_RPC_CALL CLR_QX_39824 Cannot process the call() because the RPC server (in this case CALLEE) has exceeded outstanding pending rpc call() queue limit.
DBNET_RPC_CALL RE_28710 rpc endpoint / server disconnected from dataBridges network. Try again.
DBNET_RPC_CALL AD_48621 Application does not have access to execute rpc functions.

System events for rpc call

There are a number of events which are triggered internally by the library, but can also be of use elsewhere. Below are the list of all events triggered by the library.

Below syntax is same for all system events.

//  Binding to systemevent on rpcObject  
try {
    rpcObject.bind('eventName', (payload, metadata) => {
        console.log( payload, metadata);
    });
} catch(err) {
     console.log(err.source, err.code, err.message);
}
//  Binding to systemevent on dbridgeObject  
try {
    dbridge.rpc.bind('eventName', (payload, metadata) => {
        console.log( payload, metadata);
    });
} catch(err) {
     console.log(err.source, err.code, err.message);
}
#  Binding to systemevent on rpcObject  
async def eventCallback(payload , metadata):
    print(payload , metadata)   

try:
    rpcClient.bind("eventName", eventCallback)
except dBError as e:
    print(e.code, e.source, e.message)

#  Binding to systemevent on dbridgeObject  
try:
    dbridge.rpc.bind("eventName", eventCallback)
except dBError as e:
    print(e.code, e.source, e.message)
//  Binding to systemevent on rpcObject  
Action<object,object> iRpcStatus;
try {
    rpcSvrClient.bind('eventName',  iRpcStatus = (object payload, object metadata) => {
        Console.WriteLine("{0} , {1} " , payload, metadata);
    });
} catch(dBError err){
     Console.WriteLine("{0} , {1}, {2}", err.source, err.code, err.message);
}

// Binding to systemevent on dbridgeObject
try {
    dbridge.rpc.bind('eventName', iRpcStatus = (object payload, object metadata) => {
        Console.WriteLine("{0} , {1} " , payload, metadata);
    });
} catch(dBError err){
     Console.WriteLine("{0} , {1}, {2}" , err.source, err.code, err.message);
}
Exceptions:
Source Code Description
DBLIB_RPC_CALLER INVALID_EVENTNAME Invalid Event name. Not in default events.
DBLIB_RPC_CALLER INVALID_CALLBACK Callback is not a function or is not defined.

bind_all and unbind_all

bind_all and unbind_all work much like bind and unbind, but instead of only firing callbacks on a specific event, they fire callbacks on any event, and provide that event in the metadata to the handler along with the payload.

Callback out parameter payload, metadata details are explained with each event below in this document.

Exceptions:
Source Code Description
DBLIB_CONNECT_BIND INVALID_CALLBACK If "callback function" is not declared or typeof() variable defined is not a "function".

unbind_all works similarly to unbind.

// Remove just `handler` across the rpc server 
rpcObject.unbind_all(handler);

//Remove all handlers for the all event in the subscribed/connected rpc server
rpcObject.unbind_all();

// Remove `handler` across the subscribed/connected rpc servers
dbridge.rpc.unbind_all(handler);

// Remove all handlers for all events across all subscribed/connected rpc servers
dbridge.rpc.unbind_all();
# Remove just `handler` across the rpc server 
rpcObject.unbind_all(handler)

# Remove all handlers for the all event in the subscribed/connected rpc server
rpcObject.unbind_all()

# Remove `handler` across the subscribed/connected rpc servers
dbridge.rpc.unbind_all(handler)

# Remove all handlers for all events across all subscribed/connected rpc servers
dbridge.rpc.unbind_all()
// Remove just `handler` across the rpc server 
rpcObject.unbind_all(handler);

//Remove all handlers for the all event in the subscribed/connected rpc server
rpcObject.unbind_all();

// Remove `handler` across the subscribed/connected rpc servers
dbridge.rpc.unbind_all(handler);

// Remove all handlers for all events across all subscribed/connected rpc servers
dbridge.rpc.unbind_all();

dridges:rpc.server.connect.success

Callback parameters
payload:

null

metadata (dict):
{
    "servername": "serverName" ,                    // (string) serverName to which connection is done.
    "eventname": "dbridges:rpc.server.connect.success", // (string) eventName 
}

dbridges:rpc.server.connect.fail

Callback parameters
payload: (dberror object)
{
    "source": "DBLIB_RPC_CONNECT" ,     // (string) Error source
    "code": "ACCESS_TOKEN_FAIL",            // (string) Error code 
    "message": ""                           // (string) Error message if applicable.
}
metadata (dict):
{
    "servername": "serverName" ,                // (string) serverName to which connection is done.
    "eventname": "dbridges:rpc.server.connect.fail",// (string) eventName 
}

dbridges:rpc.server.online

Callback parameters
payload:

null

metadata (dict):
{
    "servername": "serverName" ,       // (string) serverName to which connection is done.
    "eventname": "dbridges:rpc.server.online", // (string) eventName 
}

dbridges:rpc.server.offline

Callback parameters
payload:

null

metadata (dict):
{
    "servername": "serverName" ,          // (string) serverName to which connection is done.
    "eventname": "dbridges:server.offline",// (string) eventName 
}

dberror:

Source Code Description
DBNET_RPC_CONNECT ERR_FAIL_ERROR dataBridges network encountered error during current operation.
DBNET_RPC_CONNECT ERR_ACCESS_DENIED dataBridges network reported access violation during current operation.