2021-08-13 ROS笔记

/*
 * Software License Agreement (BSD License)
 *
 *  Copyright (c) 2009, Willow Garage, Inc.
 *  All rights reserved.
 *
 *  Redistribution and use in source and binary forms, with or without
 *  modification, are permitted provided that the following conditions
 *  are met:
 *
 *   * Redistributions of source code must retain the above copyright
 *     notice, this list of conditions and the following disclaimer.
 *   * Redistributions in binary form must reproduce the above
 *     copyright notice, this list of conditions and the following
 *     disclaimer in the documentation and/or other materials provided
 *     with the distribution.
 *   * Neither the name of Willow Garage, Inc. nor the names of its
 *     contributors may be used to endorse or promote products derived
 *     from this software without specific prior written permission.
 *
 *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
 *  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
 *  COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
 *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
 *  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 *  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 *  CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 *  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
 *  ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 *  POSSIBILITY OF SUCH DAMAGE.
 */

#ifndef ROSCPP_INIT_H
#define ROSCPP_INIT_H

#include "ros/forwards.h"
#include "ros/spinner.h"
#include "common.h"

namespace ros
{

namespace init_options
{
/**
 * \brief ROS初始化标志
 */
enum InitOption
{
  /**
   * Don't install a SIGINT handler.  You should install your own SIGINT handler in this
   * case, to ensure that the node gets shutdown correctly when it exits.
   * 不要安装SIGINT处理程序。 您应该在其中安装自己的SIGINT处理程序  
*，以确保节点在退出时正确关闭。  
   */
  NoSigintHandler = 1 << 0,
  /** \brief Anonymize the node name.  Adds a random number to the end of your node's name, to make it unique.
  brief节点名的匿名化。 在节点名称的末尾添加一个随机数，使其唯一。  
   */
  AnonymousName = 1 << 1,
  /**
   * \brief Don't broadcast rosconsole output to the /rosout topic
   * 不要将rosconsole输出广播到/rosout主题  
   */
  NoRosout = 1 << 2,
};
}
typedef init_options::InitOption InitOption;

/** @brief ROS initialization function.
 *
 * This function will parse any ROS arguments (e.g., topic name
 * remappings), and will consume them (i.e., argc and argv may be modified
 * as a result of this call).
 *
 * Use this version if you are using the NodeHandle API
 *
 * \param argc
 * \param argv
 * \param name Name of this node.  The name must be a base name, ie. it cannot contain namespaces.
 * \param options [optional] Options to start the node with (a set of bit flags from \ref ros::init_options)
 * \throws InvalidNodeNameException If the name passed in is not a valid "base" name
 *@brief ROS初始化功能。  
＊  
*该函数将解析任何ROS参数(例如，主题名  
* remapping)，并将消费它们(例如，argc和argv可能会被修改  
*由于这个电话的结果)。  
＊  
*如果使用NodeHandle API，请使用此版本  
＊  
* \参数命令行参数个数  
* \ param argv  
* \param name该节点的名称。 名称必须是基本名称，即。 它不能包含名称空间。  
* \param options[可选]启动节点的选项(来自\ref ros::init_options的一组位标志)  
如果传入的名字不是一个有效的base名字，则会抛出InvalidNodeNameException  
 */
ROSCPP_DECL void init(int &argc, char **argv, const std::string& name, uint32_t options = 0);

/**
 * \brief alternate ROS initialization function.
 *
 * \param remappings A map<string, string> where each one constitutes a name remapping, or one of the special remappings like __name, __master, __ns, etc.
 * \param name Name of this node.  The name must be a base name, ie. it cannot contain namespaces.
 * \param options [optional] Options to start the node with (a set of bit flags from \ref ros::init_options)
 * \throws InvalidNodeNameException If the name passed in is not a valid "base" name
简要的备用ROS初始化功能。  
＊  
* \param remappings一个map<string, string>，其中每个都构成一个名称重映射，或一个特殊的重映射，如__name， __master， __ns等。  
* \param name该节点的名称。 名称必须是基本名称，即。 它不能包含名称空间。  
* \param options[可选]启动节点的选项(来自\ref ros::init_options的一组位标志)  
如果传入的名字不是一个有效的base名字，则会抛出InvalidNodeNameException  
 */
ROSCPP_DECL void init(const M_string& remappings, const std::string& name, uint32_t options = 0);

/**
 * \brief alternate ROS initialization function.
 *
 * \param remappings A vector<pair<string, string> > where each one constitutes a name remapping, or one of the special remappings like __name, __master, __ns, etc.
 * \param name Name of this node.  The name must be a base name, ie. it cannot contain namespaces.
 * \param options [optional] Options to start the node with (a set of bit flags from \ref ros::init_options)
 * \throws InvalidNodeNameException If the name passed in is not a valid "base" name
 	简要的备用ROS初始化功能。  
＊  
一个向量<pair<string, string> >，其中每一个都构成一个名称重映射，或一个特殊的重映射，如__name， __master， __ns等。  
* \param name该节点的名称。 名称必须是基本名称，即。 它不能包含名称空间。  
* \param options[可选]启动节点的选项(来自\ref ros::init_options的一组位标志)  
如果传入的名字不是一个有效的base名字，则会抛出InvalidNodeNameException  
 */
ROSCPP_DECL void init(const VP_string& remapping_args, const std::string& name, uint32_t options = 0);

/**
 * \brief Returns whether or not ros::init() has been called
 * 返回是否调用了ros::init()  
 */
ROSCPP_DECL bool isInitialized();
/**
 * \brief Returns whether or not ros::shutdown() has been (or is being) called
 * \brief返回是否调用了ros::shutdown()  
 */
ROSCPP_DECL bool isShuttingDown();

/** \brief Enter simple event loop
 *
 * This method enters a loop, processing callbacks.  This method should only be used
 * if the NodeHandle API is being used.
 *
 * This method is mostly useful when your node does all of its work in
 * subscription callbacks.  It will not process any callbacks that have been assigned to
 * custom queues.
 *
 brief输入简单的事件循环  
＊  
*该方法进入一个循环，处理回调。 这种方法只能使用  
*如果正在使用NodeHandle API。  
＊  
*当你的节点完成所有工作时，这个方法非常有用  
*订阅回调。 它将不处理任何已分配的回调  
*自定义队列。  
＊  
 */
ROSCPP_DECL void spin();

/** \brief Enter simple event loop
 *
 * This method enters a loop, processing callbacks.  This method should only be used
 * if the NodeHandle API is being used.
 *
 * This method is mostly useful when your node does all of its work in
 * subscription callbacks.  It will not process any callbacks that have been assigned to
 * custom queues.
 *
 * \param spinner a spinner to use to call callbacks.  Two default implementations are available,
 * SingleThreadedSpinner and MultiThreadedSpinner
 * 输入简单的事件循环  
＊  
*该方法进入一个循环，处理回调。 这种方法只能使用  
*如果正在使用NodeHandle API。  
＊  
*当你的节点完成所有工作时，这个方法非常有用  
*订阅回调。 它将不处理任何已分配的回调  
*自定义队列。  
＊  
* \参数旋转器用于调用回调的旋转器。 有两种默认实现，  
* SingleThreadedSpinner和MultiThreadedSpinner  
 */
ROSCPP_DECL void spin(Spinner& spinner);
/**
 * \brief Process a single round of callbacks.
 *
 * This method is useful if you have your own loop running and would like to process
 * any callbacks that are available.  This is equivalent to calling callAvailable() on the
 * global CallbackQueue.  It will not process any callbacks that have been assigned to
 * custom queues.
 */
ROSCPP_DECL void spinOnce();

/**
 * \brief Wait for this node to be shutdown, whether through Ctrl-C, ros::shutdown(), or similar.
 */
ROSCPP_DECL void waitForShutdown();

/** \brief Check whether it's time to exit.
 *
 * ok() becomes false once ros::shutdown() has been called and is finished
 *
 * \return true if we're still OK, false if it's time to exit
 */
ROSCPP_DECL bool ok();
/**
 * \brief Disconnects everything and unregisters from the master.  It is generally not
 * necessary to call this function, as the node will automatically shutdown when all
 * NodeHandles destruct.  However, if you want to break out of a spin() loop explicitly,
 * this function allows that.
 */
ROSCPP_DECL void shutdown();

/**
 * \brief Request that the node shut itself down from within a ROS thread
 *
 * This method signals a ROS thread to call shutdown().
 */
ROSCPP_DECL void requestShutdown();

/**
 * \brief Actually starts the internals of the node (spins up threads, starts the network polling and xmlrpc loops,
 * connects to internal subscriptions like /clock, starts internal service servers, etc.).
 *
 * Usually unnecessary to call manually, as it is automatically called by the creation of the first NodeHandle if
 * the node has not already been started.  If you would like to prevent the automatic shutdown caused by the last
 * NodeHandle going out of scope, call this before any NodeHandle has been created (e.g. immediately after init())
 */
ROSCPP_DECL void start();
/**
 * \brief Returns whether or not the node has been started through ros::start()
 */
ROSCPP_DECL bool isStarted();

/**
 * \brief Returns a pointer to the global default callback queue.
 *
 * This is the queue that all callbacks get added to unless a different one is specified, either in the NodeHandle
 * or in the individual NodeHandle::subscribe()/NodeHandle::advertise()/etc. functions.
 */
ROSCPP_DECL CallbackQueue* getGlobalCallbackQueue();

/**
 * \brief searches the command line arguments for the given arg parameter. In case this argument is not found
 * an empty string is returned.
 *
 * \param argc the number of command-line arguments
 * \param argv the command-line arguments
 * \param arg argument to search for
 */
ROSCPP_DECL std::string getROSArg(int argc, const char* const* argv, const std::string& arg);

/**
 * \brief returns a vector of program arguments that do not include any ROS remapping arguments.  Useful if you need
 * to parse your arguments to determine your node name
 *
 * \param argc the number of command-line arguments
 * \param argv the command-line arguments
 * \param [out] args_out Output args, stripped of any ROS args
 */
ROSCPP_DECL void removeROSArgs(int argc, const char* const* argv, V_string& args_out);

/**
 * \brief returns the default master uri that is used if no other is specified, e.g. by defining ROS_MASTER_URI.
 */
ROSCPP_DECL const std::string& getDefaultMasterURI();

}

#endif