YARP  2.3.68+220-20170323.2+git4955ef0
Yet Another Robot Platform
yarp::os::Port Class Reference

A mini-server for network communication. More...

#include <yarp/os/Port.h>

+ Inheritance diagram for yarp::os::Port:

Public Member Functions

 Port ()
 Constructor. More...
 
virtual ~Port ()
 Destructor. More...
 
bool open (const ConstString &name)
 Start port operation, with a specific name, with automatically-chosen network parameters. More...
 
bool open (const Contact &contact, bool registerName=true)
 Start port operation with user-chosen network parameters. More...
 
bool openFake (const ConstString &name)
 Start port without making it accessible from the network. More...
 
bool addOutput (const ConstString &name)
 Add an output connection to the specified port. More...
 
bool addOutput (const ConstString &name, const ConstString &carrier)
 Add an output connection to the specified port, using a specified carrier. More...
 
bool addOutput (const Contact &contact)
 Add an output connection to the specified port, using specified network parameters. More...
 
void close ()
 Stop port activity. More...
 
virtual void interrupt ()
 Interrupt any current reads or writes attached to the port. More...
 
virtual void resume ()
 Put the port back in an operative state after interrupt() has been called. More...
 
Contact where () const
 Returns information about how this port can be reached. More...
 
bool write (PortWriter &writer, PortWriter *callback=YARP_NULLPTR) const
 Write an object to the port. More...
 
bool write (PortWriter &writer, PortReader &reader, PortWriter *callback=YARP_NULLPTR) const
 Write an object to the port, then expect one back. More...
 
bool read (PortReader &reader, bool willReply=false)
 Read an object from the port. More...
 
bool reply (PortWriter &writer)
 Send an object as a reply to an object read from the port. More...
 
bool replyAndDrop (PortWriter &writer)
 Same as reply(), but closes connection after reply. More...
 
void setReader (PortReader &reader)
 set an external writer for port data More...
 
virtual void setAdminReader (PortReader &reader)
 Set an external reader for unrecognized administrative port messages. More...
 
void setReaderCreator (PortReaderCreator &creator)
 Set a creator for readers for port data. More...
 
void enableBackgroundWrite (bool backgroundFlag)
 control whether writing from this port is done in the background. More...
 
bool isWriting ()
 Report whether the port is currently writing data. More...
 
virtual bool setEnvelope (PortWriter &envelope)
 Set an envelope (e.g., a timestamp) to the next message which will be sent. More...
 
virtual bool getEnvelope (PortReader &envelope)
 Get the envelope information (e.g., a timestamp) from the last message received on the port. More...
 
virtual int getInputCount ()
 Determine how many connections are arriving into this port. More...
 
virtual int getOutputCount ()
 Determine how many output connections this port has. More...
 
virtual void getReport (PortReport &reporter)
 Get information on the state of the port - connections etc. More...
 
virtual void setReporter (PortReport &reporter)
 Set a callback to be called upon any future connections and disconnections to/from the port. More...
 
virtual void resetReporter ()
 Remove the callback which is called upon any future connections and disconnections to/from the port. More...
 
void setAdminMode (bool adminMode=true)
 Turn on/off "admin" mode. More...
 
void setInputMode (bool expectInput)
 Configure the port to allow or forbid inputs. More...
 
void setOutputMode (bool expectOutput)
 Configure the port to allow or forbid outputs. More...
 
void setRpcMode (bool expectRpc)
 Configure the port to be RPC only. More...
 
bool setTimeout (float timeout)
 Set a timeout on network operations. More...
 
void setVerbosity (int level)
 Set whether the port should issue messages about its operations. More...
 
int getVerbosity ()
 
virtual Type getType ()
 Get the type of data the port has committed to send/receive. More...
 
virtual void promiseType (const Type &typ)
 Commit the port to a particular type of data. More...
 
virtual PropertyacquireProperties (bool readOnly)
 Access unstructured port properties. More...
 
virtual void releaseProperties (Property *prop)
 End access unstructured port properties. More...
 
virtual void includeNodeInName (bool flag)
 Choose whether to prepend a node name (if one is available) to the port's name. More...
 
bool sharedOpen (Port &port)
 
bool isOpen () const
 Check if the port has been opened. More...
 
virtual bool setCallbackLock (yarp::os::Mutex *mutex=YARP_NULLPTR)
 Add a lock to use when invoking callbacks. More...
 
virtual bool removeCallbackLock ()
 Remove a lock on callbacks added with setCallbackLock() More...
 
virtual bool lockCallback ()
 Lock callbacks until unlockCallback() is called. More...
 
virtual bool tryLockCallback ()
 Try to lock callbacks until unlockCallback() is called. More...
 
virtual void unlockCallback ()
 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...
 
virtual ConstString getName () const
 Get name of port. 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...
 

Private Member Functions

void * needImplementation () const
 
bool open (const Contact &contact, bool registerName, const char *fakeName)
 

Private Attributes

void * implementation
 
bool owned
 

Detailed Description

Constructor & Destructor Documentation

◆ Port()

Port::Port ( )

Constructor.

The port begins life in a dormant state. Call Port::open to start things happening.

Definition at line 41 of file Port.cpp.

◆ ~Port()

Port::~Port ( )
virtual

Destructor.

Definition at line 370 of file Port.cpp.

Member Function Documentation

◆ acquireProperties()

Property * Port::acquireProperties ( bool  readOnly)
virtual

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 613 of file Port.cpp.

◆ addOutput() [1/3]

bool Port::addOutput ( const ConstString name)
virtual

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 327 of file Port.cpp.

◆ addOutput() [2/3]

bool Port::addOutput ( const ConstString name,
const ConstString carrier 
)
virtual

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 331 of file Port.cpp.

◆ addOutput() [3/3]

bool Port::addOutput ( const Contact contact)
virtual

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 386 of file Port.cpp.

◆ close()

void Port::close ( )
virtual

Stop port activity.

Implements yarp::os::Contactable.

Examples:
os/simple_receiver.cpp, and os/simple_sender.cpp.

Definition at line 335 of file Port.cpp.

◆ enableBackgroundWrite()

void Port::enableBackgroundWrite ( bool  backgroundFlag)

control whether writing from this port is done in the background.

Parameters
backgroundFlagif true, calls to Port::write should return immediately

Definition at line 502 of file Port.cpp.

◆ getEnvelope()

bool Port::getEnvelope ( PortReader envelope)
virtual

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 521 of file Port.cpp.

◆ getInputCount()

int Port::getInputCount ( )
virtual

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 526 of file Port.cpp.

◆ getOutputCount()

int Port::getOutputCount ( )
virtual

Determine how many output connections this port has.

Returns
number of output connections

Implements yarp::os::Contactable.

Definition at line 532 of file Port.cpp.

◆ getReport()

void Port::getReport ( PortReport reporter)
virtual

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 538 of file Port.cpp.

◆ getType()

Type Port::getType ( )
virtual

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 605 of file Port.cpp.

◆ getVerbosity()

int Port::getVerbosity ( )
Returns
port verbosity level.

Definition at line 601 of file Port.cpp.

◆ includeNodeInName()

void Port::includeNodeInName ( bool  flag)
virtual

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 621 of file Port.cpp.

◆ interrupt()

void Port::interrupt ( )
virtual

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.

Definition at line 353 of file Port.cpp.

◆ isOpen()

bool Port::isOpen ( ) const

Check if the port has been opened.

Definition at line 633 of file Port.cpp.

◆ isWriting()

bool Port::isWriting ( )
virtual

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 508 of file Port.cpp.

◆ lockCallback()

bool Port::lockCallback ( )
virtual

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 646 of file Port.cpp.

◆ needImplementation()

void * Port::needImplementation ( ) const
private

Definition at line 29 of file Port.cpp.

◆ open() [1/3]

◆ open() [2/3]

bool Port::open ( const Contact contact,
bool  registerName = true 
)
virtual

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.

Definition at line 54 of file Port.cpp.

◆ open() [3/3]

bool Port::open ( const Contact contact,
bool  registerName,
const char *  fakeName 
)
private

Definition at line 58 of file Port.cpp.

◆ openFake()

bool Port::openFake ( const ConstString name)

Start port without making it accessible from the network.

The port is unusable for many purposes, other than sending out data to specific outputs added with addOutput().

Parameters
namean arbitrary name that connections from this port will claim to be from.
Returns
true on success

Definition at line 46 of file Port.cpp.

◆ promiseType()

void Port::promiseType ( const Type typ)
virtual

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 609 of file Port.cpp.

◆ read()

bool Port::read ( PortReader reader,
bool  willReply = false 
)
virtual

Read an object from the port.

read something 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.

Examples:
os/database.cpp, os/simple_receiver.cpp, port_power/ex0000_receiver.cpp, port_power/ex0401_give_reply.cpp, port_power/ex0500_raw_target_receiver.cpp, port_power/ex0503_serial_target_receiver.cpp, port_power/ex0505_compliant_target_receiver.cpp, and port_power/ex0507_alternative_compliant_target_receiver.cpp.

Definition at line 455 of file Port.cpp.

◆ releaseProperties()

void Port::releaseProperties ( Property prop)
virtual

End access unstructured port properties.

Parameters
propthe port property object provided by acquireProperties()

Implements yarp::os::Contactable.

Definition at line 617 of file Port.cpp.

◆ removeCallbackLock()

bool Port::removeCallbackLock ( )
virtual

Remove a lock on callbacks added with setCallbackLock()

Implements yarp::os::Contactable.

Definition at line 642 of file Port.cpp.

◆ reply()

bool Port::reply ( PortWriter writer)
virtual

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.

Examples:
os/database.cpp, and port_power/ex0401_give_reply.cpp.

Definition at line 466 of file Port.cpp.

◆ replyAndDrop()

bool Port::replyAndDrop ( PortWriter writer)
virtual

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.

Definition at line 471 of file Port.cpp.

◆ resetReporter()

void Port::resetReporter ( )
virtual

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

Implements yarp::os::Contactable.

Definition at line 550 of file Port.cpp.

◆ resume()

void Port::resume ( )
virtual

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

Implements yarp::os::Contactable.

Definition at line 361 of file Port.cpp.

◆ setAdminMode()

void Port::setAdminMode ( bool  adminMode = true)

Turn on/off "admin" mode.

With admin mode on, messages received from this port will be treated by other ports as administrative messages, rather than as data to pass on to the owner of the port.

Parameters
adminModeadministration flag

Definition at line 556 of file Port.cpp.

◆ setAdminReader()

void Port::setAdminReader ( PortReader reader)
virtual

Set an external reader for unrecognized administrative port messages.

Parameters
readerthe external reader to use

Implements yarp::os::Contactable.

Definition at line 489 of file Port.cpp.

◆ setCallbackLock()

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

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 638 of file Port.cpp.

◆ setEnvelope()

bool Port::setEnvelope ( PortWriter envelope)
virtual

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 515 of file Port.cpp.

◆ setInputMode()

void Port::setInputMode ( bool  expectInput)
virtual

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.

Definition at line 571 of file Port.cpp.

◆ setOutputMode()

void Port::setOutputMode ( bool  expectOutput)
virtual

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.

Definition at line 578 of file Port.cpp.

◆ setReader()

void Port::setReader ( PortReader reader)
virtual

set an external writer for port data

Implements yarp::os::Contactable.

Examples:
port_power/ex0300_port_callback.cpp, and port_power/ex0402_port_callback_reply.cpp.

Definition at line 483 of file Port.cpp.

◆ setReaderCreator()

void Port::setReaderCreator ( PortReaderCreator creator)

Set a creator for readers for port data.

Every port that input is received from will be automatically given its own reader. Handy if you care about the identity of the receiver.

Parameters
creatorthe "factory" for creating PortReader object

Definition at line 495 of file Port.cpp.

◆ setReporter()

void Port::setReporter ( PortReport reporter)
virtual

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 544 of file Port.cpp.

◆ setRpcMode()

void Port::setRpcMode ( bool  expectRpc)
virtual

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.

Definition at line 585 of file Port.cpp.

◆ setTimeout()

bool Port::setTimeout ( float  timeout)

Set a timeout on network operations.

Use a negative number to wait forever (this is the default behavior). Call this method early, since it won't affect connections that have already been made.

Parameters
timeoutnumber of seconds to wait for individual network operations to complete (negative to wait forever).

Definition at line 592 of file Port.cpp.

◆ setVerbosity()

void Port::setVerbosity ( int  level)

Set whether the port should issue messages about its operations.

Parameters
levelverbosity level, -1 to inhibit messages.

Definition at line 597 of file Port.cpp.

◆ sharedOpen()

bool Port::sharedOpen ( Port port)

Definition at line 625 of file Port.cpp.

◆ tryLockCallback()

bool Port::tryLockCallback ( )
virtual

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 653 of file Port.cpp.

◆ unlockCallback()

void Port::unlockCallback ( )
virtual

Unlock callbacks.

Implements yarp::os::Contactable.

Definition at line 657 of file Port.cpp.

◆ where()

Contact Port::where ( ) const
virtual

Returns information about how this port can be reached.

Returns
network parameters for this port

Implements yarp::os::Contactable.

Definition at line 380 of file Port.cpp.

◆ write() [1/2]

bool Port::write ( PortWriter writer,
PortWriter callback = YARP_NULLPTR 
) const
virtual

Write an object to the port.

write something 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.

Examples:
os/portable_pair.cpp, os/simple_sender.cpp, port_power/ex0001_sender.cpp, port_power/ex0400_expect_reply.cpp, port_power/ex0501_raw_target_sender.cpp, port_power/ex0504_serial_target_sender.cpp, port_power/ex0506_compliant_target_sender.cpp, port_power/ex0508_alternative_compliant_target_sender.cpp, and portaudio/sound_sender_mic.cpp.

Definition at line 409 of file Port.cpp.

◆ write() [2/2]

bool Port::write ( PortWriter writer,
PortReader reader,
PortWriter callback = YARP_NULLPTR 
) const
virtual

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

write something to the port

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.

Definition at line 432 of file Port.cpp.

Member Data Documentation

◆ implementation

void* yarp::os::Port::implementation
private

Definition at line 295 of file Port.h.

◆ owned

bool yarp::os::Port::owned
private

Definition at line 296 of file Port.h.


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