fipa::acl::ACLEnvelope Class Reference

ACLMessage envelope (also typed as fipa::acl::Letter) includes the base envelope and updated fields, along with the actual payload data that is wrapped by this envelope. More...

#include <acl_envelope.h>

Public Member Functions
	ACLEnvelope ()
	ACLEnvelope (const ACLMessage &msg, const fipa::acl::representation::Type &format)
void	insert (const ACLMessage &msg, const fipa::acl::representation::Type &format)
const ACLBaseEnvelopeList &	getExtraEnvelopes () const
void	addExtraEnvelope (const ACLBaseEnvelope &envelope)
void	setExtraEnvelopes (const ACLBaseEnvelopeList &envelopes)
const ACLBaseEnvelope &	getBaseEnvelope () const
void	setBaseEnvelope (const ACLBaseEnvelope &envelope)
ACLBaseEnvelope	flattened () const
AgentIDList	getDeliveryPath () const
std::string	getDeliveryPathString () const
void	setPayload (const std::string &payload)
const std::string &	getPayload () const
fipa::acl::ACLMessage	getACLMessage () const
void	stamp (const fipa::acl::AgentID &id)
bool	hasStamp (fipa::acl::AgentID id) const
ACLEnvelope	createDedicatedEnvelope (const AgentID &receiverId) const

Friends
class	EnvelopeFormat

Detailed Description

ACLMessage envelope (also typed as fipa::acl::Letter) includes the base envelope and updated fields, along with the actual payload data that is wrapped by this envelope.

See also

fipa::acl::Letter

http://www.fipa.org/specs/fipa00067/SC00067F.html

Definition at line 349 of file acl_envelope.h.

Constructor & Destructor Documentation

fipa::acl::ACLEnvelope::ACLEnvelope

(

)

Default envelope constructor

Definition at line 236 of file acl_envelope.cpp.

{}

fipa::acl::ACLEnvelope::ACLEnvelope	(	const ACLMessage &	msg,
		const fipa::acl::representation::Type &	format
	)

Creates an envelope for an acl message. Note the the acl message will be encoded according to the given representation format

Note, that the fields to, from, intended-receivers, acl-representation, payload-length, payload-encoding and date are set. All others have to be set explicitly (also see stamp). Intended-receivers is initially same as 'to' and should only be modified by a transport service to organize message delivery

Parameters

msg	ACLMessage will shall be wrapped by this envelope
format	The message format this message will be encoded in for transport

Definition at line 239 of file acl_envelope.cpp.

{
    insert(message,representation);
}

Member Function Documentation

void fipa::acl::ACLEnvelope::addExtraEnvelope ( const ACLBaseEnvelope &  envelope )

inline

Add an extra envelope to overwrite existing parameters Append the most recent extra envelope

Definition at line 417 of file acl_envelope.h.

{ mExtraEnvelopes.push_back(envelope); }

ACLEnvelope fipa::acl::ACLEnvelope::createDedicatedEnvelope

(

const AgentID &

receiverId

)

const

Create a dedicated letter, i.e. where the intended-receivers field contains only a single receiver

Returns

ACLEnvelope with an extra ACLBaseEnvelope witha single receiver

Definition at line 361 of file acl_envelope.cpp.

{
    fipa::acl::Letter updatedLetter = *this;
    fipa::acl::ACLBaseEnvelope extraEnvelope;
    AgentIDList intendedReceivers;
    intendedReceivers.push_back(receiverId);
    extraEnvelope.setIntendedReceivers(intendedReceivers);
    updatedLetter.addExtraEnvelope(extraEnvelope);

    return updatedLetter;
}

ACLBaseEnvelope fipa::acl::ACLEnvelope::flattened ( ) const

inline

Retrieve the fully merged envelope Starting with the base envelope each extra envelope is applied as an overlay

Returns

the envelope representing the most recent combination of information in base and extra envelopes

Definition at line 444 of file acl_envelope.h.

{ return mBaseEnvelope.flatten(mExtraEnvelopes); }

fipa::acl::ACLMessage fipa::acl::ACLEnvelope::getACLMessage

(

)

const

Retrieve the contained message if possible.

Returns

decoded payload

Exceptions

std::runtime_error

if the acl message could not be extracted

Definition at line 305 of file acl_envelope.cpp.

{
    using namespace fipa::acl;
    ACLMessage msg;
    MessageParser mp;
    // Get the LATEST representation (from flattened), not from base envelope!
    representation::Type aclRepresentation = flattened().getACLRepresentation();
    LOG_DEBUG_S << "getACLMessage from payload: " << mPayload << " with representation: " << representation::TypeTxt[aclRepresentation];
    if( !mp.parseData(mPayload, msg, aclRepresentation ))
    {
        // TODO This makes the process crash, only if someone decides to send us a malformed message. Not so good...
        throw std::runtime_error("ACLEnvelope::getACLMessage failed for representation '" + std::string(representation::TypeTxt[aclRepresentation]));
    }
    return msg;
}

const ACLBaseEnvelope& fipa::acl::ACLEnvelope::getBaseEnvelope ( ) const

inline

Get the base envelope

Returns

base envelope

Definition at line 430 of file acl_envelope.h.

{ return mBaseEnvelope; }

AgentIDList fipa::acl::ACLEnvelope::getDeliveryPath

(

)

const

Retrieve the delivery path from the received object in base and extra envelopes, i.e. will not include the current hop (unless stamped)

Returns

List of agents id representing the delivery path, in time order, i.e. oldest first to this agent

Definition at line 267 of file acl_envelope.cpp.

{
    AgentIDList deliveryPath;
    if(mBaseEnvelope.contains(envelope::RECEIVED_OBJECT))
    {
        std::string hop = mBaseEnvelope.getReceivedObject().getBy();
        deliveryPath.push_back(AgentID(hop));
    }

    ACLBaseEnvelopeList::const_iterator cit = mExtraEnvelopes.begin();
    for(; cit != mExtraEnvelopes.end();++cit)
    {
        if(cit->contains(envelope::RECEIVED_OBJECT))
        {
            std::string hop = cit->getReceivedObject().getBy();
            deliveryPath.push_back(AgentID(hop));
        }
    }

    return deliveryPath;
}

std::string fipa::acl::ACLEnvelope::getDeliveryPathString

(

)

const

Retrieve the delivery path as a comma separated list of agent names in time order

Returns

String representiong the delivery path

Definition at line 289 of file acl_envelope.cpp.

{
    std::string pathString;
    AgentIDList deliveryPath = getDeliveryPath();
    AgentIDList::const_iterator cit = deliveryPath.begin();
    for(; cit != deliveryPath.end();)
    {
        pathString += cit->getName();
        if(++cit != deliveryPath.end())
        {
            pathString += ",";
        }
    }
    return pathString;
}

const ACLBaseEnvelopeList& fipa::acl::ACLEnvelope::getExtraEnvelopes ( ) const

inline

Get all extra envelopes. Extra envelope represent an overlay to the base envelope, This overlay mechanism is used, since information must not be discarded.

Returns

extra envelopes

Definition at line 411 of file acl_envelope.h.

{ return mExtraEnvelopes; }

const std::string& fipa::acl::ACLEnvelope::getPayload ( ) const

inline

Get the payload which is wrapped by this envelope

Returns

string as byte container

Definition at line 473 of file acl_envelope.h.

{ return mPayload; }

bool fipa::acl::ACLEnvelope::hasStamp

(

fipa::acl::AgentID

id

)

const

Check whether the letter has already been stamped Iterates over all received objects for testing

Returns

True, if the agent id is set in one of the received objects, false otherwise

Definition at line 337 of file acl_envelope.cpp.

{
    ReceivedObject receivedObject;
    receivedObject.setBy(id.getName());

    ACLBaseEnvelopeList::const_iterator cit = mExtraEnvelopes.begin();
    for(; cit != mExtraEnvelopes.end(); ++cit)
    {
        if(cit->hasStamp(receivedObject))
        {
            return true;
        }
    }
    return false;
}

void fipa::acl::ACLEnvelope::insert	(	const ACLMessage &	msg,
		const fipa::acl::representation::Type &	format
	)

Insert a message to this envelope using a specific representation Existing settings will be overwritten

Parameters

msg	Message to be set
format	Format to be applied to the message

Definition at line 244 of file acl_envelope.cpp.

{
    using namespace fipa::acl;
    mPayload = MessageGenerator::create(message, representation);

    // infer fields from message
    mBaseEnvelope.setTo(message.getAllReceivers());
    // By default set the intended receivers
    // Can be overriden by the user when creating the base envelope,
    // however that should be avoided and only done by the transport service
    mBaseEnvelope.setIntendedReceivers(mBaseEnvelope.getTo());
    mBaseEnvelope.setFrom(message.getSender());
    // comments have to be set explicitly, so not done here
    mBaseEnvelope.setACLRepresentation(representation);
    mBaseEnvelope.setPayloadLength(mPayload.size());
    mBaseEnvelope.setPayloadEncoding(message.getEncoding());
    mBaseEnvelope.setDate(base::Time::now());

    // intended receivers, received object and transport behaviour 
    // will not be set here but have to be either explicitly 
    // or by stamping the message
}

void fipa::acl::ACLEnvelope::setBaseEnvelope ( const ACLBaseEnvelope &  envelope )

inline

Set the base envelope

Parameters

envelope

Base envelope to set

Definition at line 436 of file acl_envelope.h.

{ mBaseEnvelope = envelope; }

void fipa::acl::ACLEnvelope::setExtraEnvelopes ( const ACLBaseEnvelopeList &  envelopes )

inline

Set all extra envelopes Overwrites the existing set of extra envelopes

Parameters

envelopes

List of base envelopes

Definition at line 424 of file acl_envelope.h.

{ mExtraEnvelopes = envelopes; }

void fipa::acl::ACLEnvelope::setPayload ( const std::string &  payload )

inline

Set the payload which is wrapped by this envelope as byte get If you are using this function, make sure to set the corresponding encoding of the payload

Parameters

payload

representing an acl message

Definition at line 467 of file acl_envelope.h.

{ mPayload = payload; }

void fipa::acl::ACLEnvelope::stamp

(

const fipa::acl::AgentID &

id

)

Stamp a letter with a given agent id This creates a new received object and attaches it to an extra envelope

The mandatory fields 'by' and 'date' are set. The optional field 'id' is set.

Definition at line 321 of file acl_envelope.cpp.

{
    ReceivedObject receivedObject;

    // Mandatory fields
    receivedObject.setBy(id.getName());
    receivedObject.setDate(base::Time::now());

    receivedObject.setId(createLocalId());

    ACLBaseEnvelope extraEnvelope;
    extraEnvelope.stamp(receivedObject);

    mExtraEnvelopes.push_back(extraEnvelope);
}

Friends And Related Function Documentation

friend class EnvelopeFormat

friend

Definition at line 351 of file acl_envelope.h.

---

The documentation for this class was generated from the following files:

• /build/rock-master-18.09-multiagent-fipa-acl-0.20180914/src/message_generator/acl_envelope.h
• /build/rock-master-18.09-multiagent-fipa-acl-0.20180914/src/message_generator/acl_envelope.cpp