YARP  2.3.70.1
Yet Another Robot Platform
yarp::os::AbstractContactable Class Referenceabstract

A default implementation of an abstract port. More...

#include <yarp/os/AbstractContactable.h>

+ Inheritance diagram for yarp::os::AbstractContactable:

Public Member Functions

virtual PortasPort ()=0
 get the concrete Port being used for communication More...
 
virtual const PortasPort () const =0
 get the concrete Port being used for communication, constant version More...
 
virtual bool open (const ConstString &name) YARP_OVERRIDE
 Start port operation, with a specific name, with automatically-chosen network parameters. More...
 
virtual bool open (const Contact &contact, bool registerName=true) YARP_OVERRIDE
 Start port operation with user-chosen network parameters. More...
 
virtual bool addOutput (const ConstString &name) YARP_OVERRIDE
 Add an output connection to the specified port. More...
 
virtual bool addOutput (const ConstString &name, const ConstString &carrier) YARP_OVERRIDE
 Add an output connection to the specified port, using a specified carrier. More...
 
virtual bool addOutput (const Contact &contact) YARP_OVERRIDE
 Add an output connection to the specified port, using specified network parameters. More...
 
virtual void close () YARP_OVERRIDE
 Stop port activity. More...
 
virtual void interrupt () YARP_OVERRIDE
 Interrupt any current reads or writes attached to the port. More...
 
virtual void resume () YARP_OVERRIDE
 Put the port back in an operative state after interrupt() has been called. More...
 
virtual Contact where () const YARP_OVERRIDE
 Returns information about how this port can be reached. More...
 
virtual ConstString getName () const YARP_OVERRIDE
 Get name of port. More...
 
virtual bool setEnvelope (PortWriter &envelope) YARP_OVERRIDE
 Set an envelope (e.g., a timestamp) to the next message which will be sent. More...
 
virtual bool getEnvelope (PortReader &envelope) YARP_OVERRIDE
 Get the envelope information (e.g., a timestamp) from the last message received on the port. More...
 
virtual int getInputCount () YARP_OVERRIDE
 Determine how many connections are arriving into this port. More...
 
virtual int getOutputCount () YARP_OVERRIDE
 Determine how many output connections this port has. More...
 
virtual void getReport (PortReport &reporter) YARP_OVERRIDE
 Get information on the state of the port - connections etc. More...
 
virtual void setReporter (PortReport &reporter) YARP_OVERRIDE
 Set a callback to be called upon any future connections and disconnections to/from the port. More...
 
virtual void resetReporter () YARP_OVERRIDE
 Remove the callback which is called upon any future connections and disconnections to/from the port. More...
 
virtual bool isWriting () YARP_OVERRIDE
 Report whether the port is currently writing data. More...
 
virtual void setReader (PortReader &reader) YARP_OVERRIDE
 Set an external reader for port data. More...
 
virtual void setAdminReader (PortReader &reader) YARP_OVERRIDE
 Set an external reader for unrecognized administrative port messages. More...
 
virtual void setInputMode (bool expectInput) YARP_OVERRIDE
 Configure the port to allow or forbid inputs. More...
 
virtual void setOutputMode (bool expectOutput) YARP_OVERRIDE
 Configure the port to allow or forbid outputs. More...
 
virtual void setRpcMode (bool expectRpc) YARP_OVERRIDE
 Configure the port to be RPC only. More...
 
virtual Type getType () YARP_OVERRIDE
 Get the type of data the port has committed to send/receive. More...
 
virtual void promiseType (const Type &typ) YARP_OVERRIDE
 Commit the port to a particular type of data. More...
 
virtual PropertyacquireProperties (bool readOnly) YARP_OVERRIDE
 Access unstructured port properties. More...
 
virtual void releaseProperties (Property *prop) YARP_OVERRIDE
 End access unstructured port properties. More...
 
virtual bool write (PortWriter &writer, PortWriter *callback=YARP_NULLPTR) const YARP_OVERRIDE
 Write an object to the port. More...
 
virtual bool write (PortWriter &writer, PortReader &reader, PortWriter *callback=YARP_NULLPTR) const YARP_OVERRIDE
 Write an object to the port, then expect one back. More...
 
virtual bool read (PortReader &reader, bool willReply=false) YARP_OVERRIDE
 Read an object from the port. More...
 
virtual bool reply (PortWriter &writer) YARP_OVERRIDE
 Send an object as a reply to an object read from the port. More...
 
virtual bool replyAndDrop (PortWriter &writer) YARP_OVERRIDE
 Same as reply(), but closes connection after reply. More...
 
virtual void includeNodeInName (bool flag) YARP_OVERRIDE
 Choose whether to prepend a node name (if one is available) to the port's name. More...
 
virtual bool setCallbackLock (yarp::os::Mutex *mutex=YARP_NULLPTR) YARP_OVERRIDE
 Add a lock to use when invoking callbacks. More...
 
virtual bool removeCallbackLock () YARP_OVERRIDE
 Remove a lock on callbacks added with setCallbackLock() More...
 
virtual bool lockCallback () YARP_OVERRIDE
 Lock callbacks until unlockCallback() is called. More...
 
virtual bool tryLockCallback () YARP_OVERRIDE
 Try to lock callbacks until unlockCallback() is called. More...
 
virtual void unlockCallback () YARP_OVERRIDE
 Unlock callbacks. More...
 
- Public Member Functions inherited from yarp::os::Contactable
virtual ~Contactable ()
 Destructor. More...
 
bool open ()
 Start port operation, with automatically-chosen network parameters. More...
 
void setReadOnly ()
 Shorthand for setInputMode(true), setOutputMode(false), setRpcMode(false) More...
 
void setWriteOnly ()
 Shorthand for setInputMode(false), setOutputMode(true), setRpcMode(false) More...
 
void setRpcServer ()
 Shorthand for setInputMode(true), setOutputMode(false), setRpcMode(true) More...
 
void setRpcClient ()
 Shorthand for setInputMode(false), setOutputMode(true), setRpcMode(true) More...
 

Detailed Description

A default implementation of an abstract port.

The class hierarchy for ports is misshapen because we want to keep it SWIG compatible, and SWIG can't yet produce good translations of code that in C++ looks like multiple inheritance but is in fact just implementing multiple interfaces. There's work in SWIG on supporting interfaces, so this can be simplified a lot at that point.

Definition at line 29 of file AbstractContactable.h.

Member Function Documentation

◆ acquireProperties()

virtual Property* yarp::os::AbstractContactable::acquireProperties ( bool  readOnly)
inlinevirtual

Access unstructured port properties.

Parameters
readOnlyset this if you won't be modifying the properties.
Returns
the port properties (or YARP_NULLPTR if readOnly and none have been set)

Implements yarp::os::Contactable.

Definition at line 148 of file AbstractContactable.h.

◆ addOutput() [1/3]

virtual bool yarp::os::AbstractContactable::addOutput ( const ConstString name)
inlinevirtual

Add an output connection to the specified port.

Parameters
namethe name of the target port
Returns
true iff the connection is successfully created

Implements yarp::os::Contactable.

Definition at line 56 of file AbstractContactable.h.

◆ addOutput() [2/3]

virtual bool yarp::os::AbstractContactable::addOutput ( const ConstString name,
const ConstString carrier 
)
inlinevirtual

Add an output connection to the specified port, using a specified carrier.

Parameters
namethe name of the target port
carrierthe carrier (network protocol) to use, e.g. "tcp", "udp", "mcast", "text", ...
Returns
true iff the connection is successfully created

Implements yarp::os::Contactable.

Definition at line 60 of file AbstractContactable.h.

◆ addOutput() [3/3]

virtual bool yarp::os::AbstractContactable::addOutput ( const Contact contact)
inlinevirtual

Add an output connection to the specified port, using specified network parameters.

Parameters
contactinformation on how to reach the target
Returns
true iff the connection is successfully created

Implements yarp::os::Contactable.

Definition at line 64 of file AbstractContactable.h.

◆ asPort() [1/2]

virtual Port& yarp::os::AbstractContactable::asPort ( )
pure virtual

get the concrete Port being used for communication

Implemented in yarp::os::Publisher< T >, yarp::os::Subscriber< T >, yarp::os::RpcServer, and yarp::os::RpcClient.

◆ asPort() [2/2]

virtual const Port& yarp::os::AbstractContactable::asPort ( ) const
pure virtual

get the concrete Port being used for communication, constant version

Implemented in yarp::os::Publisher< T >, yarp::os::Subscriber< T >, yarp::os::RpcServer, and yarp::os::RpcClient.

◆ close()

virtual void yarp::os::AbstractContactable::close ( )
inlinevirtual

Stop port activity.

Implements yarp::os::Contactable.

Reimplemented in yarp::os::Subscriber< T >, and yarp::os::Publisher< T >.

Definition at line 68 of file AbstractContactable.h.

◆ getEnvelope()

virtual bool yarp::os::AbstractContactable::getEnvelope ( PortReader envelope)
inlinevirtual

Get the envelope information (e.g., a timestamp) from the last message received on the port.

You must be sure to match the type of your envelope for getEnvelope with whatever is being sent using setEnvelope. The Stamp class is a typical choice for timestamps. The Bottle class also works as an envelope, but it is not specialized to be efficient.

Parameters
enveloperecipient for envelope information for last message received by port.
Returns
true iff reading the envelope was successful

Implements yarp::os::Contactable.

Definition at line 92 of file AbstractContactable.h.

◆ getInputCount()

virtual int yarp::os::AbstractContactable::getInputCount ( )
inlinevirtual

Determine how many connections are arriving into this port.

In other words, how many other ports have this port listed as an output?

Returns
number of input connections

Implements yarp::os::Contactable.

Definition at line 96 of file AbstractContactable.h.

◆ getName()

virtual ConstString yarp::os::AbstractContactable::getName ( ) const
inlinevirtual

Get name of port.

Returns
name of port

Reimplemented from yarp::os::Contactable.

Definition at line 84 of file AbstractContactable.h.

◆ getOutputCount()

virtual int yarp::os::AbstractContactable::getOutputCount ( )
inlinevirtual

Determine how many output connections this port has.

Returns
number of output connections

Implements yarp::os::Contactable.

Definition at line 100 of file AbstractContactable.h.

◆ getReport()

virtual void yarp::os::AbstractContactable::getReport ( PortReport reporter)
inlinevirtual

Get information on the state of the port - connections etc.

PortReport::report will be called once for each connection to the port that exists right now. To request callbacks for any future connections/disconnections, use the setReporter method instead.

Parameters
reportercallback for port event/state information

Implements yarp::os::Contactable.

Definition at line 104 of file AbstractContactable.h.

◆ getType()

virtual Type yarp::os::AbstractContactable::getType ( )
inlinevirtual

Get the type of data the port has committed to send/receive.

Not all ports commit to a particular type of data.

Returns
type of data to expect/provide

Implements yarp::os::Contactable.

Definition at line 140 of file AbstractContactable.h.

◆ includeNodeInName()

virtual void yarp::os::AbstractContactable::includeNodeInName ( bool  flag)
inlinevirtual

Choose whether to prepend a node name (if one is available) to the port's name.

Node names are set using yarp::os::Node.

Parameters
flagtrue if the node name should be added to port names

Implements yarp::os::Contactable.

Definition at line 178 of file AbstractContactable.h.

◆ interrupt()

virtual void yarp::os::AbstractContactable::interrupt ( )
inlinevirtual

Interrupt any current reads or writes attached to the port.

This is useful prior to calling close(), if there are multiple threads operating on the port. Any reads or writes after the call to interrupt() will fail - unless resume() is called.

Implements yarp::os::Contactable.

Reimplemented in yarp::os::Subscriber< T >, and yarp::os::Publisher< T >.

Definition at line 72 of file AbstractContactable.h.

◆ isWriting()

virtual bool yarp::os::AbstractContactable::isWriting ( )
inlinevirtual

Report whether the port is currently writing data.

Returns
true iff the port is writing in the background.

Implements yarp::os::Contactable.

Definition at line 116 of file AbstractContactable.h.

◆ lockCallback()

virtual bool yarp::os::AbstractContactable::lockCallback ( )
inlinevirtual

Lock callbacks until unlockCallback() is called.

Has no effect if no lock has been set via a call to setCallbackLock(). Will block if callbacks are already locked.

Returns
true if callbacks were locked

Implements yarp::os::Contactable.

Definition at line 190 of file AbstractContactable.h.

◆ open() [1/2]

virtual bool yarp::os::AbstractContactable::open ( const ConstString name)
inlinevirtual

Start port operation, with a specific name, with automatically-chosen network parameters.

The port is registered with the given name, and allocated network resources, by communicating with the YARP name server.

Returns
true iff the port started operation successfully and is now visible on the YARP network

Implements yarp::os::Contactable.

Reimplemented in yarp::os::Subscriber< T >, and yarp::os::Publisher< T >.

Definition at line 48 of file AbstractContactable.h.

◆ open() [2/2]

virtual bool yarp::os::AbstractContactable::open ( const Contact contact,
bool  registerName = true 
)
inlinevirtual

Start port operation with user-chosen network parameters.

Contact information is supplied by the user rather than the name server. If the Contact information is incomplete, the name server is used to complete it (set registerName to false if you don't want name server help).

Returns
true iff the port started operation successfully and is now visible on the YARP network

Implements yarp::os::Contactable.

Reimplemented in yarp::os::Subscriber< T >, and yarp::os::Publisher< T >.

Definition at line 52 of file AbstractContactable.h.

◆ promiseType()

virtual void yarp::os::AbstractContactable::promiseType ( const Type typ)
inlinevirtual

Commit the port to a particular type of data.

Parameters
typthe type of data the port will send/receive

Implements yarp::os::Contactable.

Definition at line 144 of file AbstractContactable.h.

◆ read()

virtual bool yarp::os::AbstractContactable::read ( PortReader reader,
bool  willReply = false 
)
inlinevirtual

Read an object from the port.

Parameters
readerany object that knows how to read itself from a network connection - see for example Bottle
willReplyyou must set this to true if you intend to call reply()
Returns
true iff the object is successfully read

Implements yarp::os::UnbufferedContactable.

Reimplemented in yarp::os::RpcServer, and yarp::os::RpcClient.

Definition at line 166 of file AbstractContactable.h.

◆ releaseProperties()

virtual void yarp::os::AbstractContactable::releaseProperties ( Property prop)
inlinevirtual

End access unstructured port properties.

Parameters
propthe port property object provided by acquireProperties()

Implements yarp::os::Contactable.

Definition at line 152 of file AbstractContactable.h.

◆ removeCallbackLock()

virtual bool yarp::os::AbstractContactable::removeCallbackLock ( )
inlinevirtual

Remove a lock on callbacks added with setCallbackLock()

Implements yarp::os::Contactable.

Definition at line 186 of file AbstractContactable.h.

◆ reply()

virtual bool yarp::os::AbstractContactable::reply ( PortWriter writer)
inlinevirtual

Send an object as a reply to an object read from the port.

Only call this method if you set the willReply flag to true when you called Port::read.

Parameters
writerany object that knows how to write itself to a network connection - see for example Bottle
Returns
true iff the object is successfully written

Implements yarp::os::UnbufferedContactable.

Reimplemented in yarp::os::RpcClient.

Definition at line 170 of file AbstractContactable.h.

◆ replyAndDrop()

virtual bool yarp::os::AbstractContactable::replyAndDrop ( PortWriter writer)
inlinevirtual

Same as reply(), but closes connection after reply.

This is useful for interoperation with XML/RPC clients that do not expect to reuse a connection.

Parameters
writerany object that knows how to write itself to a network connection - see for example Bottle
Returns
true iff the object is successfully written

Implements yarp::os::UnbufferedContactable.

Reimplemented in yarp::os::RpcClient.

Definition at line 174 of file AbstractContactable.h.

◆ resetReporter()

virtual void yarp::os::AbstractContactable::resetReporter ( )
inlinevirtual

Remove the callback which is called upon any future connections and disconnections to/from the port.

Implements yarp::os::Contactable.

Definition at line 112 of file AbstractContactable.h.

◆ resume()

virtual void yarp::os::AbstractContactable::resume ( )
inlinevirtual

Put the port back in an operative state after interrupt() has been called.

Implements yarp::os::Contactable.

Reimplemented in yarp::os::Subscriber< T >, and yarp::os::Publisher< T >.

Definition at line 76 of file AbstractContactable.h.

◆ setAdminReader()

virtual void yarp::os::AbstractContactable::setAdminReader ( PortReader reader)
inlinevirtual

Set an external reader for unrecognized administrative port messages.

Parameters
readerthe external reader to use

Implements yarp::os::Contactable.

Definition at line 124 of file AbstractContactable.h.

◆ setCallbackLock()

virtual bool yarp::os::AbstractContactable::setCallbackLock ( yarp::os::Mutex mutex = YARP_NULLPTR)
inlinevirtual

Add a lock to use when invoking callbacks.

mutex.lock() will be called before and mutex.unlock() will be called after the callback. This applies at least to callbacks set by setReader and setAdminReader, and in future may apply to other callbacks.

Parameters
mutexthe lock to use. If YARP_NULLPTR, a mutex will be allocated internally by the port, and destroyed with the port.

Implements yarp::os::Contactable.

Definition at line 182 of file AbstractContactable.h.

◆ setEnvelope()

virtual bool yarp::os::AbstractContactable::setEnvelope ( PortWriter envelope)
inlinevirtual

Set an envelope (e.g., a timestamp) to the next message which will be sent.

You must be sure to match the type of your envelope for setEnvelope with whatever will be read using getEnvelope. The Stamp class is a typical choice for timestamps. The Bottle class also works as an envelope, but it is not specialized to be efficient.

Currently, for proper operation, the envelope must serialize correctly in text-mode (even if you do not explicitly use text-mode connections). Bottle or Stamp are good choices.

Parameters
envelopeinformation to add to the next message which will be sent
Returns
true iff setting the envelope was successful

Implements yarp::os::Contactable.

Definition at line 88 of file AbstractContactable.h.

◆ setInputMode()

virtual void yarp::os::AbstractContactable::setInputMode ( bool  expectInput)
inlinevirtual

Configure the port to allow or forbid inputs.

By default, ports allow anything.

Parameters
expectInputset to true if this port will be used for input

Implements yarp::os::Contactable.

Reimplemented in yarp::os::RpcServer, and yarp::os::RpcClient.

Definition at line 128 of file AbstractContactable.h.

◆ setOutputMode()

virtual void yarp::os::AbstractContactable::setOutputMode ( bool  expectOutput)
inlinevirtual

Configure the port to allow or forbid outputs.

By default, ports allow anything.

Parameters
expectOutputset to true if this port will be used for output

Implements yarp::os::Contactable.

Reimplemented in yarp::os::RpcServer, and yarp::os::RpcClient.

Definition at line 132 of file AbstractContactable.h.

◆ setReader()

virtual void yarp::os::AbstractContactable::setReader ( PortReader reader)
inlinevirtual

Set an external reader for port data.

Parameters
readerthe external reader to use

Implements yarp::os::Contactable.

Reimplemented in yarp::os::Subscriber< T >, and yarp::os::Publisher< T >.

Definition at line 120 of file AbstractContactable.h.

◆ setReporter()

virtual void yarp::os::AbstractContactable::setReporter ( PortReport reporter)
inlinevirtual

Set a callback to be called upon any future connections and disconnections to/from the port.

To get information on the current connections that exist, use the getReport method instead.

Parameters
reportercallback for port event/state information

Implements yarp::os::Contactable.

Definition at line 108 of file AbstractContactable.h.

◆ setRpcMode()

virtual void yarp::os::AbstractContactable::setRpcMode ( bool  expectRpc)
inlinevirtual

Configure the port to be RPC only.

By default all ports can be used for RPC or streaming communication.

Parameters
expectRpcset to true if this port will be used for RPC only

Implements yarp::os::Contactable.

Reimplemented in yarp::os::RpcServer, and yarp::os::RpcClient.

Definition at line 136 of file AbstractContactable.h.

◆ tryLockCallback()

virtual bool yarp::os::AbstractContactable::tryLockCallback ( )
inlinevirtual

Try to lock callbacks until unlockCallback() is called.

Has no effect if no lock has been set via a call to setCallbackLock(). Returns immediately.

Returns
true if callbacks were locked by this call, false if they were already locked.

Implements yarp::os::Contactable.

Definition at line 194 of file AbstractContactable.h.

◆ unlockCallback()

virtual void yarp::os::AbstractContactable::unlockCallback ( )
inlinevirtual

Unlock callbacks.

Implements yarp::os::Contactable.

Definition at line 198 of file AbstractContactable.h.

◆ where()

virtual Contact yarp::os::AbstractContactable::where ( ) const
inlinevirtual

Returns information about how this port can be reached.

Returns
network parameters for this port

Implements yarp::os::Contactable.

Definition at line 80 of file AbstractContactable.h.

◆ write() [1/2]

virtual bool yarp::os::AbstractContactable::write ( PortWriter writer,
PortWriter callback = YARP_NULLPTR 
) const
inlinevirtual

Write an object to the port.

Parameters
writerany object that knows how to write itself to a network connection - see for example Bottle
callbackobject on which to call onCompletion() after write is done (otherwise writer.onCompletion() is called)
Returns
true iff the object is successfully written

Implements yarp::os::UnbufferedContactable.

Reimplemented in yarp::os::RpcServer.

Definition at line 156 of file AbstractContactable.h.

◆ write() [2/2]

virtual bool yarp::os::AbstractContactable::write ( PortWriter writer,
PortReader reader,
PortWriter callback = YARP_NULLPTR 
) const
inlinevirtual

Write an object to the port, then expect one back.

Parameters
writerany object that knows how to write itself to a network connection - see for example Bottle
readerany object that knows how to read itself from a network connection - see for example Bottle
callbackobject on which to call onCompletion() after write is done (otherwise writer.onCompletion() is called)
Returns
true iff an object is successfully written and read

Implements yarp::os::UnbufferedContactable.

Reimplemented in yarp::os::RpcServer.

Definition at line 161 of file AbstractContactable.h.


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