openc2lib.core.producer

 1""" OpenC2 Producer functions
 2
 3	This module provides the `Producer` class for implementing an OpenC2 Producer.
 4
 5"""
 6from openc2lib.core.message import Command, Message
 7from openc2lib.core.encoder import Encoder
 8from openc2lib.core.transfer import Transfer
 9
10class Producer:
11	"""
12		OpenC2 Producer
13
14		An OpenC2 Producer sends Commands and receives Responses. The `Producer` is an intermediary to 
15		deal with OpenC2-related issues, but does not implement any control logic. A `Producer` instance
16		is used to create an OpenC2 stack with an `Encoder` and a `Transfer` protocol. The `Producer`
17		is associated to an identifier to distinguish its messages.	
18
19		Note that the actuator instance is only known to the consumer, which runs it. The producer 
20		 knows the profile of the actuator, which embeds the an identifier for the actual
21		 actuator run by the consumer.
22		"""
23	def __init__(self, producer: str, encoder: Encoder =None, transfer: Transfer =None):
24		""" Initialize an OpenC2 stack
25
26			Creates a `Producer` communication stack made of an identifier, an Encoding format, and a 
27			Transfer protocol. This will be used as the "default" stack if no otherwise overwritten
28			when sending the message.
29			Both the Encoding and Transfer class must be derived from the base `Encoder` and `Transfer` definition.
30
31			:param producer: A string that identifies the `Producer`.
32			:param encoder: An instance of an Encoding class derived from base `Encoder`.
33			:param transfer: An instnace of a Transfer protocol derived from base `Transfer`.
34		"""
35		if not isinstance(producer, str):
36			raise TypeError('Only strings are allowed for producer identifier')
37		self.producer = producer
38		self.encoder = encoder
39		self.transfer = transfer
40
41	def sendcmd(self, cmd: Command, encoder: Encoder =None, transfer: Transfer =None, consumers: [] =None):
42		""" Send an OpenC2 message
43
44			Sends an openc2lib `Command`. The default communication stack is used, if a different one is not specified. 
45			This method internally creates the `Message` metadata that will be encoded and traferred.
46			
47			The option to
48			create a different stack is given to manage the presence of multiple `Consumer` with different stacks.
49			However, it is recommended to create different `Producer`s in this case.
50			Note that the `consumer` argument is meant for internal use of a `Consumer` only, because the
51			endpoint of the message is always identified by the `Transfer` definition.
52
53
54			:param cmd: The `Command` to be sent.
55			:param encoder: An instance of an Encoding class derived from base `Encoder`.
56			:param transfer: An instnace of a Transfer protocol derived from base `Transfer`.
57			:param consumers: An optional list of strings that identify multiple intended recipients of the
58				message.
59			:return: The `Response` to the `Command`.
60		"""
61		if not encoder: encoder = self.encoder
62		if not transfer: transfer = self.transfer
63		if not transfer: raise ValueError('Missing transfer object')
64		if not encoder: raise ValueError('Missing encoder object')
65		
66		msg = Message(cmd)
67		msg.from_=self.producer
68		msg.to=consumers
69
70		return transfer.send(msg, encoder)