Native Messaging Interfaces and Classes for C++

This section describes the interfaces and classes associated with the Native Messaging.

RequestAgent

class NativeMessaging::RequestAgent : public virtual CORBA_Object

The Request Agent interface defines operations of the Native Messaging Request Agent.

Include File

Include the NativeMessaging_c.hh file when you use this class.

IDL definition

module NativeMessaging {
interface RequestAgent {

exception DuplicatedRequestTag {};
exception PollingGroupIsEmpty {};
exception RequestNotExist {};


Request create_request(
in RequestDesc desc) raises (DuplicatedRequestTag);

RequestTagSeq poll(
in string polling_group,
in unsigned long timeout,
in boolean unmask) raises
(PollingGroupIsEmpty);

void destroy_request(
in Request req) raises (RequestNotExist);

};
};

RequestAgent Methods

create_request

virtual ::CORBA::Object_ptr create_request(
const NativeMessaging::RequestDesc& _desc);

This method creates and returns an asynchronous method invocation request object in the Request Agent.

Parameter	Description
_desc	The RequestDesc structure containing information about the target object and async request.

The method throws DuplicatedRequestTag exception.

poll

virtual NativeMessaging::RequestTagSeq* poll(const char* _polling_group, ::CORBA::Ulong _timeout, ::CORBA::Boolean _umask);

The method returns the sequence of request tags whose replies are ready.

Parameter	Description
_polling_group	The name of the polling group
_timeout	The timeout interval in "milliseconds" to wait if the polling group has no readily available replies. The values have following meanings: • timeout > 0 poll will block for that much time. If after the timeout, there are still no replies available, an empty sequence of request tags is returned. • timeout=0 poll will not block. If there are any replies available, their tags will be returned to the caller. If there are no replies available, an empty sequence is returned. • timeout < 0 (or timeout=2^(32-1)) poll will block until a reply is available.
_unmask	If this flag is false, subsequent calls to poll on the same polling group will also return the request tags returned in the previous polls, until those request get destroyed either as a result of manual or automatic trash. If this flag is true, once a request tag is returned in the poll, it will not appear in subsequent polls.

This method throws PollingGroupIsEmpty exception.

destroy_request

virtual void destroy_request(::CORBA::Object_ptr _req);

This method destroys an async request.

Parameter	Description
_req	The async request object reference to be destroyed.

This method throws RequestNotExist exception.

RequestDesc

struct NativeMessaging::RequestDesc;

A descriptor structure containing all the information needed to service a async request.

Include File

Include the NativeMessaging_c.hh file when you use this struct.

IDL Definition

module NativeMessaging {
typedef Object Request;
typedef sequence<octet> OctetSeq;
typedef OctetSeq RequestTag;
typedef sequence<RequestTag> RequestTagSeq;
typedef OctetSeq Cookie;

struct RequestDesc {
Object target;
string repository_id;
ReplyRecipient reply_recipient;
Cookie the_cookie;
string polling_group;
RequestTag request_tag;
PropertySeq properties;
};
};

RequestDesc Fields

 

Field	Description
target	Reference of the target object, on which client wish to invoke an operation. CORBA::BAD_PARAM exception will result if a null value is passed.
repository_id	Repository id of the target object. If this is an empty string, request agent will try to extract the rep id from the target object reference. If rep id empty here and also null or empty in the target IOR reference, a CORBA::BAD_PARAM exception is thrown. Clients can also use a repository id of *. This acts as a wild card and is_a operation on the request object returns true for any repository id.
reply_recipient	The reference of the reply recipient (or reply handler) when using callback model. If this reference is not null then the Request Agent will call its reply_available method when a reply is ready.
the_cookie	A user specified sequence of octets. It will be sent to the reply_recipient when reply_available is called. The information inside the cookie is user defined.
polling_group	A user assigned polling group name. The group name is scoped inside the Request Agent. Group names are not uniquely used. If a non-empty group name string is assigned and the Request Agent doesn't have a polling group with the same name, a new group with that name will be implicitly created. However, if a group already exists, the created request object is inserted into that group.
request_tag	User assigned. If non-empty, it uniquely identifies the request in the group. If another request in the group has the same tag, create_request method throws DuplicatedRequestTag exception.
properties	Sequence of Property structure. Currently only one Property value is defined (see Property structure)

ReplyRecipient

class NativeMessaging::ReplyRecipient : public virtual CORBA_Object

Defines the interface for callback reply recipient.

Include File

Include the NativeMessaging_c.hh file when you use this class.

module NativeMessaging {
interface ReplyRecipient {
void reply_available(
in Request reply_holder,
in string operation,
in Cookie the_Cookie);
};
};

ReplyRecipient methods

reply_available

virtual void reply_available(::CORBA::Object_ptr _reply_holder, const char* _operation, const NativeMessaging::OctetSeq& _the_Cookie);

Parameter	Description
_reply_holder	async request for which reply is received.
_operation	operation invoked by the client.
_the_Cookie	cookie passed by the client when creating the request.

REPLY_NOT_AVAILABLE

This constant defines the CORBA::NO_RESPONSE exception minor code value thrown by the RequestAgent to the polling client when the reply for a request is not available.

Include File

Include the NativeMessaging_c.hh file when you use this constant.

IDL definition

module NativeMessaging {
const unsigned long REPLY_NOT_AVAILABLE = 100;
};

Property

struct NativeMessaging::Property;

Holds a symbolic property name and its value inside an CORBA::Any.

Include File

Include the NativeMessaging_c.hh file when you use this struct.

IDL definition

module NativeMessaging {
struct Property {
string name;
any value;
};
};

Property Fields

 

Field	Description
name	The name of the property. Currently only one name is recognized: RequestManualTrash
value	The value of the property. The RequestManualTrash has a value of type boolean: If set to true, the request is destroyed manually by calling destroy_request method. If set to false, the request is destroyed automatically once the reply is read (default).

PropertySeq

class NativeMessaging::PropertySeq : private VISResource

A Sequence of Property that is passed inside RequestDesc while creating async Request.

Include File

Include the NativeMessaging_c.hh file when you use this class.

OctetSeq

class NativeMessaging::OctetSeq : private VISResource

This class represents a sequence of octets. Similar to CORBA::OctetSeq but defined here to make the NativeMessaging.idl independent of any other IDL.

Include File

Include the NativeMessaging_c.hh file when you use this class.

RequestTag

typedef OctetSeq RequestTag;

An octet sequence identifying a request inside a polling group.

Include File

Include the NativeMessaging_c.hh file when you use this class.

RequestTagSeq

class NativeMessaging::RequestTagSeq : private VISResource

Instances of this class are returned by the RequestAgent's poll method when group polling is performed. Each element in the sequence is a RequestTag; the octet sequence identifying a request inside the polling group.

Include File

Include the NativeMessaging_c.hh file when you use this class.

Cookie

typedef OctetSeq Cookie

An octet sequence that is passed inside RequestDesc while creating async Request. The contents inside the Cookie are user defined. The Request Agent passes this Cookie to ReplyRecipient's reply_available method when callback occurs.

Include File

Include the NativeMessaging_c.hh file when you use this type.

DuplicatedRequestTag

class DuplicatedRequestTag : public CORBA_UserException

This class defines a UserException that is raised if the async request is created with a polling group name specified and the there is another request in the polling group with the same request tag.

Include File

Include the NativeMessaging_c.hh file when you use this class.

PollingGroupIsEmpty

class PollingGroupIsEmpty : public CORBA_UserException

This class defines a UserException that is raised if poll method is called on the RequestAgent and:

1	There is no group with the specified name.

2	The polling group exists but contains no requests that are waiting for replies.

Include File

Include the NativeMessaging_c.hh file when you use this class.

RequestNotExist

class RequestNotExist : public CORBA_UserException

This class defines a UserException that is raised if the destroy_request method is called on RequestAgent and the specified request could not be found or is already destroyed.

Include File

Include the NativeMessaging_c.hh file when you use this class.