The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Net-IMP-Remote-0.010
River stage zero No dependents
++
/ Net::IMP::Remote::Protocol

NAME

Net::IMP::Remote::Protocol - protocol description for IMP RPC

DESCRIPTION

Basic Ideas

  • There is a single connection between data provider and IMP RPC server per factory, e.g. no separate connections per analyzer. This enables fast creation and teardown of analyzers.

  • Most messages are asynchronous, e.g. expect no reply, so that the analyzer can continue even if the messages are not fully send yet. Only get_interface is synchronous.

Messages from Data Provider to IMP RPC Server

set_version(version)

This exchanges the version of the protocol spoken. It is the first operation of IMP RPC server after a new client connected. The client will verify the version and close if it cannot speak it.

get_interface( list<data_type, list<result_type>> provider_ifs )

This sends the interface supported by the data provider and returns the matching interfaces from the IMP plugins inside the IMP RPC server. It's the only synchronous operation, expecting a interface message back. It will be called after establishing the connection, before any analyzers are created.

set_interface( <data_type, list<result_type>> provider_if )

This will be called by the data provider to fix the interface to the given one. If this given interface is not supported an exception will be generated asynchronously. But this should usually not happen, because the supported interfaces were queried before with get_interface. This function should be called after get_interface and before creating analyzers.

new_analyzer( analyzer_id, hash context )

This will create a new analyzer. The uniq integer analyzer_id will be created by the data provider, so that the operation can be done asynchronously. The analyzer_Id will be used in subsequent data, result or exception calls in the context of the new analyzer. The analyzer_id should not be 0. The context is expected as a hash with string keys and string values.

If the IMP plugin is not interested in analyzing data inside the given context it can simply send IMP_PASS for both directions with offset set to IMP_MAX_OFFSET.

delete_analyzer( analyzer_id )

This will cause the deletion of the analyzer with the given analyzer_id.

data( analyzer_id, dir, offset, data_type_id, char data[] )

This will send data from the data provider into the IMP plugin. For the meaning of the parameters see Net::IMP interface.

Messages back from IMP RPC Server

exception(analyzer_id, char msg[])

This notifies the data provider about problems with the given analyzer, which will usually result in closing the analyzer. If analyzer_id is 0 it will be interpreted as an exception for the whole factory and the factory including all analyzers should better shut down.

interface( list<data_type, list<result_type>> analyzer_ifs

This is the reply message to a get_interface message from the data provider.

result( analyzer_id, result_type, ... )

This will return the result for processing data. The arguments following the result_type are specific to the type, e.g.

IMP_PASS|IMP_PREPASS: dir,offset
IMP_REPLACE: dir,offset, char newdata[]
IMP_DENY: dir, char reason[], char key1[], char value1[], ....
IMP_DROP: no more arguments
IMP_FATAL: char reason[]
IMP_TOSENDER: dir, char data[]
IMP_PAUSE: dir
IMP_CONTINUE: dir
IMP_REPLACE_LATER: dir,offset,endoffset
IMP_LOG: dir,offset,len,level,char msg[], char key1[], char value1[], ....
IMP_ACCTFIELD: string key, char value[]