ArNetworking: ArMapChanger Class Reference

- Main Page
- Classes
- Related Pages

- Alphabetical List
- Class List
- Class Hierarchy
- Class Members

# ArMapChanger Class Reference

`#include <ArMapChanger.h>`

List of all members.

## Detailed Description

Utility class used to apply incremental changes to an Aria map.

ArMapChanger is a helper class that can send and receive ArMapChangeDetails over the network and apply them to an associated Aria map. An instance of ArMapChanger must be instantiated on both the client and the server side. (Note that there are two different versions of the constructors for this.)

TODO: Possibly subclass this into ArClientMapChanger and ArServerMapChanger?

See also:
  ArMapChangeDetails

## Public Member Functions
virtual bool | addChangeCB (ArFunctor2< ArServerClient *, std::list< ArNetPacket * > * > *functor)
| Adds a callback to be invoked after the map has been changed on the server.
virtual void | addPostWriteFileCB (ArFunctor *functor, ArListPos::Pos position=ArListPos::LAST)
| Adds a callback to be invoked after the map file has been written.
virtual void | addPreWriteFileCB (ArFunctor *functor, ArListPos::Pos position=ArListPos::LAST)
| Adds a callback to be invoked before the map file is written.
virtual bool | applyMapChanges (ArMapChangeDetails *changeDetails)
| Applies the given map changes received from the client to the associated Aria map.
| ArMapChanger (ArMapInterface *map)
| Constructs a stand-alone map changer that will apply changes to the given map.
| ArMapChanger (ArClientBase *client, const std::list< std::string > &infoNames)
| Constructs a client map changer.
| ArMapChanger (ArServerBase *server, ArMapInterface *map)
| Constructs a server map changer.
virtual bool | remChangeCB (ArFunctor2< ArServerClient *, std::list< ArNetPacket * > * > *functor)
| Removes a callback from the map change list.
virtual void | remPostWriteFileCB (ArFunctor *functor)
| Removes a callback from the post-write file list.
virtual void | remPreWriteFileCB (ArFunctor *functor)
| Removes a callback from the pre-write file list.
virtual bool | sendMapChanges (ArMapChangeDetails *changeDetails)
| Sends the given map changes from the client to the server.
virtual bool | sendPacketList (const std::list< ArNetPacket * > &packetList)
| Transmits the given map change packet list from the client to the server.
virtual | ~ArMapChanger ()
| Destructor.
## Static Public Attributes
static const char * | CHANGES_IN_PROGRESS_PACKET_NAME
| Name of a network packet that is broadcast when the map is being changed.
static const char * | PROCESS_CHANGES_PACKET_NAME
| Name of the network packet that contains the incremental map changes.
## Protected Types
enum | { CHANGE_DATA_TYPE_COUNT = LAST_CHANGE_DATA_TYPE + 1, CHANGE_COMMAND_COUNT = LAST_CHANGE_COMMAND + 1, MAX_POINTS_IN_PACKET = 1000, MAX_LINES_IN_PACKET = 500 }
| Miscellaneous constants.
enum | MapChangeCommand { START_CHANGES = 0, CONTINUE_CHANGES = 1, FINISH_CHANGES = 2, CANCEL_CHANGES = 3, LAST_CHANGE_COMMAND = CANCEL_CHANGES }
| Indicates the current stage of the map change network packets. More...
enum | MapChangeDataType { NO_CHANGE = 0, SUMMARY_DATA = 1, INFO_DATA = 2, SUPPLEMENT_DATA = 3, OBJECTS_DATA = 4, POINTS_DATA = 5, LINES_DATA = 6, LAST_CHANGE_DATA_TYPE = LINES_DATA }
| Type of data contained in the map change network packet. More...
enum | MapChangeReplyType { CHANGE_FAILED = 0, CHANGE_SUCCESS = 10 }
| Reply status for a map change request.
## Protected Member Functions
bool | addFileLineSetPackets (MapChangeDataType dataType, ArMapChangeDetails::MapLineChangeType changeType, const char *scanType, const char *extra, ArMapFileLineSet *fileLineSet, std::list< ArNetPacket * > *packetListOut)
| Creates network packets for the specified map change data and adds them to the given list.
bool | addFileLineToPacketList (MapChangeDataType dataType, ArMapChangeDetails::MapLineChangeType changeType, const char *scanType, const ArMapFileLine &fileLine, std::list< ArNetPacket * > *packetListOut)
| Creates network packets for the specified file line and adds them to the given list.
bool | addGroupToPacketList (MapChangeDataType dataType, ArMapChangeDetails::MapLineChangeType changeType, const char *scanType, ArMapFileLineGroup &group, std::list< ArNetPacket * > *packetListOut)
| Creates network packets for the specified file line group and adds them to the given list.
void | addHeaderToPacket (MapChangeCommand command, MapChangeDataType dataType, ArMapChangeDetails::MapLineChangeType changeType, const char *scanType, ArNetPacket *packet)
| Inserts header information into the given network packet.
bool | addLinesPackets (ArMapChangeDetails::MapLineChangeType changeType, const char *scanType, std::vector< ArLineSegment > *lineSegmentList, std::list< ArNetPacket * > *packetListOut)
| Creates network packets for the given map data lines and adds them to the given list.
bool | addPointsPackets (ArMapChangeDetails::MapLineChangeType changeType, const char *scanType, std::vector< ArPose > *pointList, std::list< ArNetPacket * > *packetListOut)
| Creates network packets for the given map data points and adds them to the given list.
void | addToCallbackList (ArFunctor *functor, ArListPos::Pos position, std::list< ArFunctor * > *cbList)
| Adds the given functor to the given callback list.
bool | applyInfoChanges (ArMapChangeDetails *changeDetails)
| Applies the given map changes to the info data in the map.
bool | applyObjectChanges (ArMapChangeDetails *changeDetails)
| Applies the given map changes to the object data in the map.
bool | applyScanChanges (ArMapChangeDetails *changeDetails, const char *scanType, ArFileParser &parser)
| Applies scan data changes for the specified scan type.
bool | applyScanChanges (ArMapChangeDetails *changeDetails)
| Applies all scan data changes that are contained in the given change details.
bool | applySupplementChanges (ArMapChangeDetails *changeDetails)
| Applies the given map changes to the supplemental data in the map.
bool | convertChangeDetailsToPacketList (ArMapChangeDetails *changeDetails, std::list< ArNetPacket * > *packetListOut, bool isRelay=false)
| Creates a list of network packets for the given map change details.
bool | convertPacketListToChangeDetails (std::list< ArNetPacket * > &packetList, ArMapChangeDetails *changeDetailsOut)
| Unpacks the given network packet list and populates the given map change details.
virtual void | handleChangePacket (ArServerClient *client, ArNetPacket *packet)
| Server handler for packets that contain map change details.
virtual void | handleChangeReplyPacket (ArNetPacket *packet)
| Client handler for the results of applying the map changes on the server.
virtual void | handleChangesInProgressPacket (ArNetPacket *packet)
| Client handler for the map-changes-in-progress broadcast packet.
virtual void | handleClientShutdown ()
| Client handler for when the robot disconnects or is shutdown.
virtual void | handleIdleProcessingPacket (ArNetPacket *packet)
| Client handler for the server's idle-processing-pending broadcast packet.
bool | isIdleProcessingPending ()
| Determines whether idle processing is pending on the server.
bool | isMatchingObjects (ArMapObject *obj1, ArMapObject *obj2)
| Determines whether the two given map objects are the same object.
void | remFromCallbackList (ArFunctor *functor, std::list< ArFunctor * > *cbList)
| Removes the given functor from the given callback list.
void | resetPacketList (std::list< ArNetPacket * > *packetList)
| Resets all of the network packets in the given list so that they can be read again.
bool | unpackFileLineSet (ArNetPacket *packet, MapChangeDataType dataType, ArMapChangeDetails::MapLineChangeType changeType, const char *scanType, int *numGroups, int *numChildren, ArMapChangeDetails *changeDetails)
| Unpacks the specified file line set from the given network packet.
bool | unpackHeader (ArNetPacket *packet, MapChangeCommand *commandOut, ArMapId *origMapIdOut, ArMapId *newMapIdOut=NULL, MapChangeDataType *dataTypeOut=NULL, ArMapChangeDetails::MapLineChangeType *changeTypeOut=NULL, std::string *scanTypeOut=NULL)
| Unpacks the header data from the given network packet.
bool | unpackLines (ArNetPacket *packet, ArMapChangeDetails::MapLineChangeType changeType, const char *scanType, int *numLines, ArMapChangeDetails *changeDetails)
| Unpacks the map data lines for the specified scan from the given network packet.
bool | unpackPoints (ArNetPacket *packet, ArMapChangeDetails::MapLineChangeType changeType, const char *scanType, int *numPoints, ArMapChangeDetails *changeDetails)
| Unpacks the map data points for the specified scan from the given network packet.
bool | waitForReply (ArTime &started)
| Waits for a reply from the server.
## Protected Attributes
std::list< ArFunctor2< ArServerClient *, std::list< ArNetPacket * > * > * > | myChangeCBList
| List of server client callbacks to be invoked after the map has been changed.
ArMapChangeDetails * | myChangeDetails
| Change details to apply to the Aria map.
ArClientBase * | myClient
| Associated client base; non-NULL only when changer instantiated on the client.
ClientChangeInfo * | myClientInfo
| Information regarding the server client that is currently sending map changes.
ArMutex | myClientInfoMutex
| Mutex that protects access to the myClientInfo member.
ArMutex | myClientMutex
| Mutex that protects access to the myClient member.
ArFunctorC< ArMapChanger > | myClientShutdownCB
| Handler invoked when the client shuts down.
ArFunctor2C< ArMapChanger, ArServerClient *, ArNetPacket * > | myHandleChangePacketCB
| Server handler for the network packets that describe map chagnes.
ArFunctor1C< ArMapChanger, ArNetPacket * > | myHandleChangesInProgressPacketCB
| Client handler for the map-changes-in-progress packet.
ArFunctor1C< ArMapChanger, ArNetPacket * > | myHandleIdleProcessingPacketCB
| Client handler for the idle-processing-in-progress packet.
ArFunctor1C< ArMapChanger, ArNetPacket * > | myHandleReplyPacketCB
| Client handler for the reply packet.
ArMutex | myIdleProcessingMutex
| Mutex that protects access to the myIsIdleProcessingPending member.
std::list< std::string > | myInfoNames
| List of info types in the associated info map.
ArMutex | myInterleaveMutex
| Mutex that protects access to the interleave data.
bool | myIsIdleProcessingPending
| Whether the server has data to process once it becomes idle.
bool | myIsWaitingForReturn
| Whether the client is waiting for a reply from the server.
ArMapInterface * | myMap
| Aria map currently in use.
std::list< ArFunctor * > | myPostWriteCBList
| List of callbacks to be invoked after the changed map file is written.
std::list< ArFunctor * > | myPreWriteCBList
| List of callbacks to be invoked before the changed map file is written.
bool | myReadyForNextPacket
| Whether the client is ready to send another packet.
ArServerBase * | myServer
| Associated server base; non-NULL only when changer instantiated on the server.
ArMapInterface * | myWorkingMap
| Copy of the current Aria map, used to make sure the changes can be successfully made.
## Classes
struct | ClientChangeInfo
| Accumulates the packet list that describes map changes received from a specified client. More...

## Member Enumeration Documentation

enum ArMapChanger::MapChangeCommand`[protected]`

Indicates the current stage of the map change network packets.

Enumerator:

  START_CHANGES | First packet that contains changes to be applied to the map.
  CONTINUE_CHANGES | Request to continue applying changes to the map.
  FINISH_CHANGES | Last packet that contains changes to be applied to the map.
  CANCEL_CHANGES | Cancel the request to change the map.
  LAST_CHANGE_COMMAND | Last value in the enumeration.

enum ArMapChanger::MapChangeDataType`[protected]`

Type of data contained in the map change network packet.

Enumerator:

  NO_CHANGE | No change data.
  SUMMARY_DATA | Summary data, e.g. min/max pos, number of points.
  INFO_DATA | Any of the info data, e.g. MapInfo, RouteInfo.
  SUPPLEMENT_DATA | Miscellaneous supplemental data such as origin lat/long/alt.
  OBJECTS_DATA | Map objects, i.e. Cairn lines.
  POINTS_DATA | Map data points.
  LINES_DATA | Map data lines.
  LAST_CHANGE_DATA_TYPE | Last value in the enumeration.

## Constructor & Destructor Documentation

ArMapChanger::ArMapChanger | ( | ArServerBase * | server,
|  | ArMapInterface * | map |
| ) |  |  |

Constructs a server map changer.

The map changer will automatically apply the received map change details to the given map.

Parameters:

  | server | the ArServerBase * that receives the network packets
  | map | the ArMapInterface * to which to apply the map changes

ArMapChanger::ArMapChanger | ( | ArClientBase * | client,
|  | const std::list< std::string > & | infoNames |
| ) |  |  |

Constructs a client map changer.

The map changer will send map change details to the server. The application must request this by calling sendMapChanges.

Parameters:

  | client | the ArClientBase * which is used to send the map change details
  | infoNames | the list of info names included in the map

ArMapChanger::ArMapChanger | ( | ArMapInterface * | map | ) |

Constructs a stand-alone map changer that will apply changes to the given map.

This method is primarily used for debugging.

Parameters:

  | map | the ArMapInterface * to which to apply the map changes

## Member Function Documentation

virtual bool ArMapChanger::addChangeCB | ( | ArFunctor2< ArServerClient *, std::list< ArNetPacket * > * > * | functor | ) | `[virtual]`

Adds a callback to be invoked after the map has been changed on the server.

This method is primarily used on the central server. After the map changes are successfully applied to its map, they are propagated to all of the connected robots.

bool ArMapChanger::addFileLineSetPackets | ( | MapChangeDataType | dataType,
|  | ArMapChangeDetails::MapLineChangeType | changeType,
|  | const char * | scanType,
|  | const char * | extra,
|  | ArMapFileLineSet * | fileLineSet,
|  | std::list< ArNetPacket * > * | packetListOut |
| ) |  |  | `[protected]`

Creates network packets for the specified map change data and adds them to the given list.

Parameters:

  | dataType | the MapChangeDataType that specifies which map data is to be added
  | changeType | the MapLineChangeType that specifies the type of map change (lines added or deleted)
  | scanType | the char * identifier of the scan source to add; valid only when dataType is SUMMARY_DATA
  | extra | an optional const char * identifier that clarifies which data to add; when dataType is INFO_DATA, this is the info name; otherwise, ignored
  | fileLineSet | the ArMapFileLineSet * component of the map change details that is to be converted to network packets
  | packetListOut | the list of ArNetPackets to which new packets are added

void ArMapChanger::addHeaderToPacket | ( | MapChangeCommand | command,
|  | MapChangeDataType | dataType,
|  | ArMapChangeDetails::MapLineChangeType | changeType,
|  | const char * | scanType,
|  | ArNetPacket * | packet |
| ) |  |  | `[protected]`

Inserts header information into the given network packet.

Parameters:

  | command | the MapChangeCommand that specifies which command identifier to add to this packet
  | dataType | the MapChangeDataType that specifies which map data is to be added
  | changeType | the MapLineChangeType that specifies the type of map change (lines added or deleted)
  | scanType | the char * identifier of the scan source to add; valid only when dataType is SUMMARY_DATA
  | packet | the ArNetPacket * to be modified; must be non-NULL

virtual void ArMapChanger::addPostWriteFileCB | ( | ArFunctor * | functor,
|  | ArListPos::Pos | position = `ArListPos::LAST` |
| ) |  |  | `[virtual]`

Adds a callback to be invoked after the map file has been written.

This method is primarily used to restore the server's directory write status, if necessary.

virtual void ArMapChanger::addPreWriteFileCB | ( | ArFunctor * | functor,
|  | ArListPos::Pos | position = `ArListPos::LAST` |
| ) |  |  | `[virtual]`

Adds a callback to be invoked before the map file is written.

This method is primarily used to temporarily make the server's directory writeable, if necessary.

bool ArMapChanger::applyInfoChanges | ( | ArMapChangeDetails * | changeDetails | ) | `[protected]`

Applies the given map changes to the info data in the map.

Parameters:

  | changeDetails | the ArMapChangeDetails * that describes how the map should be modified; must be non-NULL

bool ArMapChanger::applyObjectChanges | ( | ArMapChangeDetails * | changeDetails | ) | `[protected]`

Applies the given map changes to the object data in the map.

Parameters:

  | changeDetails | the ArMapChangeDetails * that describes how the map should be modified; must be non-NULL

bool ArMapChanger::applyScanChanges | ( | ArMapChangeDetails * | changeDetails,
|  | const char * | scanType,
|  | ArFileParser & | parser |
| ) |  |  | `[protected]`

Applies scan data changes for the specified scan type.

Parameters:

  | changeDetails | the ArMapChangeDetails * that describes how the map should be modified; must be non-NULL
  | scanType | the char * identifier of the scan type to be updated
  | parser | the ArFileParser used to parse the changeDetails

bool ArMapChanger::applyScanChanges | ( | ArMapChangeDetails * | changeDetails | ) | `[protected]`

Applies all scan data changes that are contained in the given change details.

Scan data include summary data, map data points, and map data lines. If the map contains scan data for multiple sources, then this method applies all of the applicable changes.

An Aria map must have been previously associated with the map changer.

bool ArMapChanger::applySupplementChanges | ( | ArMapChangeDetails * | changeDetails | ) | `[protected]`

Applies the given map changes to the supplemental data in the map.

Parameters:

  | changeDetails | the ArMapChangeDetails * that describes how the map should be modified; must be non-NULL

bool ArMapChanger::isMatchingObjects | ( | ArMapObject * | obj1,
|  | ArMapObject * | obj2 |
| ) |  |  | `[protected]`

Determines whether the two given map objects are the same object.

If the objects have a name, then the name must be identical. Otherwise, the type and position must be the same.

bool ArMapChanger::unpackFileLineSet | ( | ArNetPacket * | packet,
|  | MapChangeDataType | dataType,
|  | ArMapChangeDetails::MapLineChangeType | changeType,
|  | const char * | scanType,
|  | int * | numGroups,
|  | int * | numChildren,
|  | ArMapChangeDetails * | changeDetails |
| ) |  |  | `[protected]`

Unpacks the specified file line set from the given network packet.

The file line set is added to the given change details.

bool ArMapChanger::unpackHeader | ( | ArNetPacket * | packet,
|  | MapChangeCommand * | commandOut,
|  | ArMapId * | origMapIdOut,
|  | ArMapId * | newMapIdOut = `NULL`,
|  | MapChangeDataType * | dataTypeOut = `NULL`,
|  | ArMapChangeDetails::MapLineChangeType * | changeTypeOut = `NULL`,
|  | std::string * | scanTypeOut = `NULL` |
| ) |  |  | `[protected]`

Unpacks the header data from the given network packet.

Parameters:

  | packet | the ArNetPacket * from which to extract the header information; must be non-NULL
  | commandOut | the MapChangeCommand * extracted from the packet
  | origMapIdOut | the original ArMapId * extracted from the packet
  | newMapIdOut | the optional new ArMapId * extracted from the packet
  | dataTypeOut | the optional MapChangeDataType * extracted from the packet
  | changeTypeOut | the optional MapLineChangeType * extracted from the packet
  | scanTypeOut | the optional std::string * extracted from the packet

Returns:
  bool true if all of the header information was succesfully extracted; false, otherwise

bool ArMapChanger::unpackLines | ( | ArNetPacket * | packet,
|  | ArMapChangeDetails::MapLineChangeType | changeType,
|  | const char * | scanType,
|  | int * | numLines,
|  | ArMapChangeDetails * | changeDetails |
| ) |  |  | `[protected]`

Unpacks the map data lines for the specified scan from the given network packet.

The data lines are added to the given change details.

bool ArMapChanger::unpackPoints | ( | ArNetPacket * | packet,
|  | ArMapChangeDetails::MapLineChangeType | changeType,
|  | const char * | scanType,
|  | int * | numPoints,
|  | ArMapChangeDetails * | changeDetails |
| ) |  |  | `[protected]`

Unpacks the map data points for the specified scan from the given network packet.

The data points are added to the given change details.

bool ArMapChanger::waitForReply | ( | ArTime & | started | ) | `[protected]`

Waits for a reply from the server.

If a reply is not received within 30 seconds, this method will timeout and return false.

Returns:
  bool true if the reply was received; false otherwise

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

- ArMapChanger.h