Microsoft Information Protection (MIP) SDK for C++: Reference 1.15
Doxygen-generated documentation for MIP SDK written in C++
Loading...
Searching...
No Matches
execution_state.h
Go to the documentation of this file.
1/*
2 *
3 * Copyright (c) Microsoft Corporation.
4 * All rights reserved.
5 *
6 * This code is licensed under the MIT License.
7 *
8 * Permission is hereby granted, free of charge, to any person obtaining a copy
9 * of this software and associated documentation files(the "Software"), to deal
10 * in the Software without restriction, including without limitation the rights
11 * to use, copy, modify, merge, publish, distribute, sublicense, and / or sell
12 * copies of the Software, and to permit persons to whom the Software is
13 * furnished to do so, subject to the following conditions :
14 *
15 * The above copyright notice and this permission notice shall be included in
16 * all copies or substantial portions of the Software.
17 *
18 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.IN NO EVENT SHALL THE
21 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
22 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
23 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
24 * THE SOFTWARE.
25 *
26 */
27/**
28 * @brief This file contains the ExecutionState class.
29 *
30 * @file execution_state.h
31 */
32#ifndef API_MIP_UPE_EXECUTION_STATE_H_
33#define API_MIP_UPE_EXECUTION_STATE_H_
34
35#include <map>
36#include <memory>
37#include <utility>
38#include <vector>
39
40#include "mip/common_types.h"
41#include "mip/mip_namespace.h"
43#include "mip/upe/action.h"
46#include "mip/upe/label.h"
49
50MIP_NAMESPACE_BEGIN
51
53
54 /**
55 * @brief Audit metadata keys in string representation.
56 */
57 inline std::string Sender() { return "Sender"; }
58 inline std::string Recipients() { return "Recipients"; }
59 inline std::string LastModifiedBy() { return "LastModifiedBy"; }
60 inline std::string LastModifiedDate() { return "LastModifiedDate"; }
61}
62
63/**
64 * @brief Interface for all the state needed to execute the engine.
65 *
66 * @note Clients should only call the methods to obtain the state that is needed.
67 * Hence, for efficiency, clients may want to implement this interface such that
68 * the corresponding state is computed dynamically instead of computing in advance.
69 */
71public:
72 /**
73 * @brief Gets the sensitivity label ID that should be applied on the document.
74 *
75 * @return sensitivity label ID to be applied to the content if exists else empty to remove label.
76 */
77 virtual std::shared_ptr<Label> GetNewLabel() const = 0;
78
79 /**
80 * @brief Gets the content description that describes the document.
81 * example for a file: [path\filename]
82 * example for an email: [Subject:Sender]
83 *
84 * @return content description to be applied to the content.
85 *
86 * @note This value is used by auditing as a human-readable description of the content
87 */
88 virtual std::string GetContentIdentifier() const = 0;
89
90 /**
91 * @brief Return an identifier which correlates application events with the corresponding audit or protection service REST requests.
92 *
93 * @return An identifier (usually specified as a GUID)
94 */
95 virtual std::string GetApplicationScenarioId() const {
96 return std::string();
97 };
98
99 /**
100 * @brief Gets the state of the content while the application is interacting with it.
101 *
102 * @return State of the content data
103 */
104 virtual DataState GetDataState() const {
105 return DataState::USE;
106 };
107
108 /**
109 * @brief Implementation should pass if justification to downgrade an existing label was given.
110 *
111 * @return true if downgrade is justified--along with the justification message--else false
112 * @see mip::JustifyAction
113 */
114 virtual std::pair<bool, std::string> IsDowngradeJustified() const = 0;
115
116 /**
117 * @brief Get the new label's assignment method.
118 *
119 * @return the assignment method STANDARD, PRIVILEGED, AUTO.
120 * @see mip::AssignmentMethod
121 */
123
124 /**
125 * @brief Return new label's extended properties
126 *
127 * @return the extended properties applied to the content.
128 */
129 virtual std::vector<std::pair<std::string, std::string>> GetNewLabelExtendedProperties() const {
130 return std::vector<std::pair<std::string, std::string>>();
131 }
132
133 /**
134 * @brief Get the meta-data items from the content.
135 *
136 * @return the metadata applied to the content.
137 * @note Each metadata item is a pair of name and value.
138 */
139 virtual std::vector<MetadataEntry> GetContentMetadata(
140 const std::vector<std::string>& names,
141 const std::vector<std::string>& namePrefixes) const = 0;
142
143 /**
144 * @brief Get the Protection Descriptor
145 *
146 * @return the Protection Descriptor
147 */
148 virtual std::shared_ptr<ProtectionDescriptor> GetProtectionDescriptor() const = 0;
149
150 /**
151 * @brief Gets the content format.
152 *
153 * @return content format
154 */
155 virtual std::string GetContentFormat() const = 0;
156
157 /**
158 * @brief Gets the highest metadata version supported by the application for the tenant.
159 *
160 * @return Content metadata version. If 0, metadata is un-versioned.
161 * @note If a file format supports multiple versions of metadata,
162 * this allows MIP to understand all metadata and report granular metadata changes on a per-version basis.
163 */
167
168 /**
169 * @brief Gets a masked enum describing all the supported action types.
170 *
171 * @return a masked enum describing all the supported action types.
172 *
173 * @note ActionType::Justify must be supported. When a policy and label change requires justification,
174 * a justification action will always be returned.
175 */
176 virtual ActionType GetSupportedActions() const = 0;
177
178 /**
179 * @brief Return a map of classification results.
180 *
181 * @param classificationIds a list of classification IDs.
182 * @return a list of classification results.
183 * @note return nullptr if no classification cycle executed.
184 */
185 virtual std::shared_ptr<ClassificationResults> GetClassificationResults(
186 const std::vector<std::shared_ptr<ClassificationRequest>>& /*classificationIds*/) const {
187 return nullptr;
188 }
189
190 /**
191 * @brief Return a map of application specific audit key-value pairs.
192 *
193 * @return a list of application specific audit metadata
194 *
195 * @note Registered Key:Value pairs
196 * Sender: Email Id for the sender
197 * Recipients: Represents a JSON array of recipients for an email
198 * LastModifiedBy: Email Id for the user who last modified the content
199 * LastModifiedDate: Date the content was last modified
200 */
201 virtual std::map<std::string, std::string> GetAuditMetadata() const {
202 return std::map<std::string, std::string>();
203 }
204
205 /** @cond DOXYGEN_HIDE */
206 virtual ~ExecutionState() { }
207
208protected:
209 ExecutionState() { }
210 /** @endcond */
211};
212
213MIP_NAMESPACE_END
214
215#endif // API_MIP_UPE_EXECUTION_STATE_H_
A file containing the Action base class and the ActionType enumerator.
ActionType
Different action types.
Definition action.h:46
Interface for all the state needed to execute the engine.
virtual std::shared_ptr< ClassificationResults > GetClassificationResults(const std::vector< std::shared_ptr< ClassificationRequest > > &) const
Return a map of classification results.
virtual std::shared_ptr< Label > GetNewLabel() const =0
Gets the sensitivity label ID that should be applied on the document.
virtual std::vector< std::pair< std::string, std::string > > GetNewLabelExtendedProperties() const
Return new label's extended properties.
virtual std::pair< bool, std::string > IsDowngradeJustified() const =0
Implementation should pass if justification to downgrade an existing label was given.
virtual std::string GetApplicationScenarioId() const
Return an identifier which correlates application events with the corresponding audit or protection s...
virtual std::shared_ptr< ProtectionDescriptor > GetProtectionDescriptor() const =0
Get the Protection Descriptor.
virtual MetadataVersion GetContentMetadataVersion() const
Gets the highest metadata version supported by the application for the tenant.
virtual std::string GetContentFormat() const =0
Gets the content format.
virtual ActionType GetSupportedActions() const =0
Gets a masked enum describing all the supported action types.
virtual DataState GetDataState() const
Gets the state of the content while the application is interacting with it.
virtual AssignmentMethod GetNewLabelAssignmentMethod() const =0
Get the new label's assignment method.
virtual std::vector< MetadataEntry > GetContentMetadata(const std::vector< std::string > &names, const std::vector< std::string > &namePrefixes) const =0
Get the meta-data items from the content.
virtual std::string GetContentIdentifier() const =0
Gets the content description that describes the document.
virtual std::map< std::string, std::string > GetAuditMetadata() const
Return a map of application specific audit key-value pairs.
Interface for a MetadataVersion.
This file contains the ClassificationRequest class.
This file contains the ClassificationResult class.
A file Containing the common types used by the upe, file and protection modules.
AssignmentMethod
The assignment method of the label on the document.
DataState
Defines what state of the data is the application acting upon.
@ USE
Active data under constant change stored physically in databases/file/warehouses etc.
This file contains the Label class.
This file contains the MetadataEntry class.
A file containing the MetadataVersion class and the MetadataVersionFormat enumerator.
MIP namespace macros.
std::string Sender()
Audit metadata keys in string representation.
std::string LastModifiedBy()
std::string LastModifiedDate()
std::string Recipients()
Defines ProtectionDescriptor interface.