DDS (Data Distribution Service) 数据分发服务-规范中文翻译_007
2.以数据为中心的订阅发布(DCPS)
2.2 平台无关模型(Platform Independent Model ,PIM)
2.2.2 平台无关模型(PIM)描述
2.2.2.2 域模块
2.2.2.2.1 DomainParticipant类
2.2.2.2.1.7 create_contentfilteredtopic
此方法将创建一个ContentFilteredTopic。如2.2.2.3主题定义模块中所述,ContentFilteredTopic可用于实现基于内容的订阅。
订阅的相关主题是通过related_topic参数指定的。ContentFilteredTopic仅与在该主题下发布的数据样本有关系,并根据其内容进行过滤。通过评估样本中某些数据字段值的逻辑表达式来完成过滤。逻辑表达式来源于filter_expression和expression_parameters参数。
过滤表达式和参数的语法在附录B中描述。
如果调用失败,将返回“nil”值(由平台指定)。
2.2.2.2.1.8 delete_ contentfilteredtopic
此方法将删除一个ContentFilteredTopic。
如果还有存在的DataReader,DataWriter,ContentFilteredTopic或MultiTopic需要使用该Topic,则无法将该Topic删除。在这种情况下调用delete_topic方法,将返回PRECONDITION_NOT_MET。
必须在创建Topic的同一DomainParticipant对象上调用delete_topic方法。如果在另一个DomainParticipant上调用delete_topic,该方法将不起作用,返回PRECONDITION_NOT_MET。
除标准错误代码外,还可能返回错误代码:PRECONDITION_NOT_MET。
2.2.2.2.1.9 create_multitopic
此方法创建MultiTopic。如2.2.2.3 主题定义模块中所述,MultiTopic可用于订阅多个主题,并将接收的数据组合/过滤为作为结果的类型。特别地,MultiTopic提供了基于内容的订阅机制。
作为结果的类型由type_name参数指定。在创建MultiTopic之前,必须在服务中完成该类型的注册。这是在TypeSupport接口的派生类上使用register_type方法完成的,如2.2.2.3.6中所述。
subscription_expression和expression_parameters参数指定主题列表,并组合过滤与重新排列每个主题信息的逻辑。
表达式和参数的语法在附录B中描述。
如果调用失败,将返回“nil”值(由平台指定)。
2.2.2.2.1.10 delete_multitopic
此方法将删除一个MultiTopic。
如果还有存在的DataReader对象需要使用该MultiTopic,则无法将该MultiTopic删除。在这种情况下调用delete_multitopic方法,将返回PRECONDITION_NOT_MET。
必须在创建MultiTopic的同一DomainParticipant对象上调用delete_multitopic方法。 如果在其他DomainParticipant上调用delete_multitopic,该方法将不起作用,返回PRECONDITION_NOT_MET。
除标准错误代码外,还可能返回错误代码:PRECONDITION_NOT_MET。
2.2.2.2.1.11 find_topic
find_topic方法使用Topic的名称和超时时间作为参数,可根据参数传入的名称访问现有(或准备存在)的主题。
如果已经存在同名Topic,本方法便可以访问该主题,否则等待(阻塞调用者),直到其他机制创建该主题(或设定的时间到期超时)。这个其他机制可以是另一个线程,配置工具或一些其他中间件服务。需要注意的是,Topic是一个本地对象,充当指定主题全局概念的“代理”。中间件可以选择传播主题并在本地获取远程创建主题的信息。
通过find_topic获取的主题必须通过delete_topic删除,确保释放本地资源。如果通过find_topic或create_topic多次获取主题,那必须使用delete_topic删除相同次数的主题。
无论中间件是否选择传播主题,delete_topic操作都只删除本地代理。
如果方法超时,则返回“nil”值(由平台指定)。
2.2.2.2.1.12 lookup_topicdescription
lookup_topicdescription方法将TopicDescription的name作为参数,根据参数传入的名称访问现有的本地创建的TopicDescription。
如果已经存在同名的TopicDescription,本方法便可以访问该对象,否则返回“nil”值。本方法永远不会阻塞。
lookup_topicdescription方法可用于定位任何本地创建的Topic,ContentFilteredTopic和MultiTopic对象。
与find_topic方法不同,lookup_topicdescription方法仅在本地创建的主题中搜索。因此,它永远不应该创建新的TopicDescription。lookup_topicdescription返回的TopicDescription不需要额外删除。在一种特殊情况下可以删除lookup_topicdescription方法返回的TopicDescription,即该TopicDescription没有读者或写者,会被删除,后续对其查找将失败。
如果本方法无法找到TopicDescription,则返回“nil”值(由平台指定)。
2.2.2.2.1.13 get_builtin_subscriber
此方法允许访问内置Subscriber。每个DomainParticipant都包含几个内置的Topic对象,以及相应的DataReader对象来访问这些Topic对象。所有这些DataReader对象都属于单个内置Subscriber。
内置主题用于传递有关其他DomainParticipant,Topic,DataReader和DataWriter对象的信息。这些内置对象在2.2.5内置主题中描述。
2.2.2.2.1.14 ignore_participant
此方法允许应用程序指导中间件服务在本地忽略远程域参与者。从那时起,服务将在本地运行,就好像远程参与者不存在一样。这意味着它将忽略源自该域参与者的任何主题,发布或订阅。
该方法可以与通过“DCPSParticipant”内置主题实现远程参与者的发现结合使用,以提供不同功能(例如访问控制)。应用程序数据可以通过USER_DATA QoS策略与DomainParticipant相关联。此应用程序数据作为内置主题中的字段传播,辅助应用程序实现其自己的访问控制策略。有关内置主题的更多详细信息,请参见2.2.5内置主题。
要忽略的域参与者由handle参数标识。此句柄是SampleInfo中出现的句柄,该SampleInfo通过主题为“DCPSParticipant”的内置DataReader收取。使用与任何DataReader相同的读取/获取操作读取内置DataReader。这些数据访问方法将在2.2.2.5 订阅模块中描述。
ignore_participant方法不需要是可逆的。服务无法撤销。
除标准错误代码外,还可能返回错误代码:OUT_OF_RESOURCES。
2.2.2.2.1.15 ignore_topic
此方法允许应用程序指导中间件服务在本地忽略主题,意味着它将在本地忽略某一主题的任何发布或订阅操作。
当应用程序知道它永远不会在某些主题下发布或订阅数据时,此方法可用于节约本地资源。
要忽略的主题由handle参数标识。此句柄是从主题为“DCPSTopic”的内置DataReader接收到的数据样本SampleInfo中获得的句柄。
ignore_topic方法不需要是可逆的。服务无法撤销。
除标准错误代码外,还可能返回错误代码:OUT_OF_RESOURCES。
2.2.2.2.1.16 ignore_publication
此方法允许应用程序指导中间件服务在本地忽略远程发布; 发布由主题名称、用户数据与Publisher设置的分块的关联定义(请参阅2.2.5中的“DCPSPublication”内置主题)。在此调用之后,服务将忽略与该发布有关的任何数据。
要忽略的DataWriter由handle参数标识。此句柄是从主题为“DCPSPublication”的内置DataReader接收到的数据样本SampleInfo中获得的句柄。
ignore_publication操作不需要是可逆的。服务无法撤销。
除标准错误代码外,还可能返回错误代码:OUT_OF_RESOURCES。
2.2.2.2.1.17 ignore_subscription
此方法允许应用程序指导中间件服务在本地忽略远程订阅; 订阅由主题名称、用户数据与Subscriber设置的分块的关联定义(请参阅2.2.5中的“DCPSSubscription”内置主题)。 在此调用之后,服务将忽略与该订阅有关的任何数据。
要忽略的DataReader由handle参数标识。此句柄是在从主题为“DCPSSubscription”的内置DataReader接收到的数据样本SampleInfo中获得的句柄。
ignore_subscription操作不需要是可逆的。服务无法撤销。
除标准错误代码外,还可能返回错误代码:OUT_OF_RESOURCES。
2.2.2.2.1.18 delete_contained_entities
此方法将删除通过DomainParticipant的“create”方法创建的所有实体,即删除所有包含的Publisher,Subscriber,Topic,ContentFilteredTopic和MultiTopic实体对象。
在删除每个包含的实体对象之前,此方法将递归地调用每个包含的实体对象上的相应delete_contained_entities方法(如果适用),递归地使用该模式。通过这种方式,DomainParticipant上的delete_contained_entities方法将最终删除DomainParticipant中递归包含的所有实体对象,例如DataWriter,DataReader对象,以及隶属于所包含的DataReader对象的QueryCondition和ReadCondition对象。
如果任何包含的实体处于无法删除的状态,方法将返回PRECONDITION_NOT_MET。
一旦delete_contained_entities成功返回,应用程序可能会删除DomainParticipant,因为应用程序知道它没有包含的实体。