register()

register(topicURI, rpc[, advancedOptions])

RPC registration for invocation.

Parameters:

  • topicURI. Required. A string that identifies the remote procedure to be called. Must meet a WAMP Spec URI requirements.

  • rpc. Required. registered procedure.

  • advancedOptions. Optional parameters hash table. Must include any or all of the options:

    • match: string matching policy ("prefix"|"wildcard")

    • invoke: string invocation policy ("single"|"roundrobin"|"random"|"first"|"last")

Returns promise:

  • Resolved with one hash-table parameter with following attributes:

    • topic

    • requestId

    • registrationId

  • Rejected with one of the Errors instances

Registered PRC during invocation will receive one hash-table argument with following attributes:

  • argsList: array payload (maybe omitted)

  • argsDict: object payload (maybe omitted)

  • details: some invocation options object. One attribute of interest in options is "receive_progress" (boolean), which indicates, that caller is willing to receive progressive results, if possible. Another one is "trustlevel", which indicates the call trust level, assigned by dealer (of course if it is configured accordingly).

  • result_handler: result handler for case when you want to send progressive results. Just call it with one parameter, same as you return from simple invocation. Also, do not forget to set options: { progress: true } for intermediate results.

  • error_handler: error handler for case when you want to send progressive results and caught some exception or error.

RPC can return no result (undefined), any single value, array or hash-table object:

  • If it is an array - it is sent as is as WAMP positional arguments attribute

  • If it is a single object (without argsList and argsDict keys) - it is sent as is as WAMP key-value arguments attribute

  • If it is a single Number/String/Boolean/Null value - it is packed into a one-item array and is sent as WAMP positional arguments attribute. Be aware that the receiver will get it in argsList as a one-item array and not a. O single value!

  • It is possible to pass the array and object-like data simultaneously. In this case, pass a hash-table with the next attributes:

    • argsList: array payload (may be omitted)

    • argsDict: object payload (may be omitted)

    • options: some result options object. The possible attribute of options is "progress": true, which indicates, that it's a progressive result, so there will be more results in the future. Be sure to unset "progress" on the last result message.

const sqrt_f = function (data) { return { result: data.argsList[0]*data.argsList[0] } };

await ws.register('sqrt.value', sqrt_f);

try {
    await ws.register('sqrt.value', sqrt_f);
    console.log('RPC successfully registered');
} catch (e) {
    console.log('RPC registration failed!', e);
}

Also, wampy supports rpc with asynchronous code, such as some user interactions or xhr, using promises. For using this functionality in old browsers you should use polyfills, like es6-promise. Check browser support at can i use site.

const getUserName = function () {
    return new Promise(function (resolve, reject) {
        /* Ask user to input his username somehow,
           and resolve promise with user input at the end */
        resolve({ argsList: userInput });
    });
};

ws.register('get.user.name', getUserName);

Also, it is possible to abort rpc processing and throw error with custom application specific data. This data will be passed to caller onError callback.

Exception object with custom data may have next attributes:

  • error. String with custom error uri. Must meet a WAMP Spec URI requirements.

  • details. Custom details dictionary object.

  • argsList. Custom arguments array, this will be forwarded to the caller by the WAMP router's dealer role. In most cases this attribute is used to pass the human-readable message to the client.

  • argsDict. Custom arguments object, this will be forwarded to the caller by the WAMP router's dealer role.

Note: Any other type of errors (like built in Javascript runtime TypeErrors, ReferenceErrors) and exceptions are caught by wampy and sent back to the client's side, not just this type of custom errors. In this case the details of the error can be lost.

const getSystemInfo = function () {

    // Application logic

    // for example, you need to get data from db
    // and at this time you can't connect to db
    // you can throw exception with some details for client application

    const UserException = function () {
        this.error = 'app.error.no_database_connection';
        this.details = {
         errorCode: 'ECONNREFUSED',
         errorMessage: 'Connection refused by a remote host.',
         database: 'db',
         host: '1.2.3.4',
         port: 5432,
         dbtype: 'postgres'
       };
        this.argsList = ['Not able to connect to the database.'];
        this.argsDict = {};
    };

    throw new UserException();
};

await wampy.register('get.system.info', getSystemInfo);
try {
    await wampy.call('get.system.info');
} catch (e) {
    console.log('Error happened', e);
}

Previouscancel()Nextunregister()

Last updated