[mirror_edk2.git] / MdePkg / Include / Protocol / RegularExpressionProtocol.h

/** @file\r
  This section defines the Regular Expression Protocol. This protocol isused to match\r
  Unicode strings against Regular Expression patterns.\r
\r
Copyright (c) 2015-2018, Intel Corporation. All rights reserved.<BR>\r
This program and the accompanying materials are licensed and made available under\r
the terms and conditions of the BSD License that accompanies this distribution.\r
The full text of the license may be found at\r
http://opensource.org/licenses/bsd-license.php.\r
\r
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
  @par Revision Reference:\r
  This Protocol was introduced in UEFI Specification 2.5.\r
\r
**/\r
\r
#ifndef __REGULAR_EXPRESSION_PROTOCOL_H__\r
#define __REGULAR_EXPRESSION_PROTOCOL_H__\r
\r
#define EFI_REGULAR_EXPRESSION_PROTOCOL_GUID \\r
  { \\r
    0xB3F79D9A, 0x436C, 0xDC11, {0xB0, 0x52, 0xCD, 0x85, 0xDF, 0x52, 0x4C, 0xE6 } \\r
  }\r
\r
#define EFI_REGEX_SYNTAX_TYPE_POSIX_EXTENDED_GUID \\r
  { \\r
    0x5F05B20F, 0x4A56, 0xC231, {0xFA, 0x0B, 0xA7, 0xB1, 0xF1, 0x10, 0x04, 0x1D } \\r
  }\r
\r
#define EFI_REGEX_SYNTAX_TYPE_PERL_GUID \\r
  { \\r
    0x63E60A51, 0x497D, 0xD427, {0xC4, 0xA5, 0xB8, 0xAB, 0xDC, 0x3A, 0xAE, 0xB6 } \\r
  }\r
\r
#define EFI_REGEX_SYNTAX_TYPE_ECMA_262_GUID \\r
  { \\r
    0x9A473A4A, 0x4CEB, 0xB95A, {0x41, 0x5E, 0x5B, 0xA0, 0xBC, 0x63, 0x9B, 0x2E } \\r
  }\r
\r
typedef struct _EFI_REGULAR_EXPRESSION_PROTOCOL  EFI_REGULAR_EXPRESSION_PROTOCOL;\r
\r
\r
typedef struct {\r
  CONST CHAR16 *CapturePtr; // Pointer to the start of the captured sub-expression\r
                            // within matched String.\r
\r
  UINTN        Length;      // Length of captured sub-expression.\r
} EFI_REGEX_CAPTURE;\r
\r
typedef EFI_GUID EFI_REGEX_SYNTAX_TYPE;\r
\r
//\r
// Protocol member functions\r
//\r
/**\r
  Returns information about the regular expression syntax types supported\r
  by the implementation.\r
\r
  This                     A pointer to the EFI_REGULAR_EXPRESSION_PROTOCOL\r
                           instance.\r
\r
  RegExSyntaxTypeListSize  On input, the size in bytes of RegExSyntaxTypeList.\r
                           On output with a return code of EFI_SUCCESS, the\r
                           size in bytes of the data returned in\r
                           RegExSyntaxTypeList. On output with a return code\r
                           of EFI_BUFFER_TOO_SMALL, the size of\r
                           RegExSyntaxTypeListrequired to obtain the list.\r
\r
  RegExSyntaxTypeList      A caller-allocated memory buffer filled by the\r
                           driver with one EFI_REGEX_SYNTAX_TYPEelement\r
                           for each supported Regular expression syntax\r
                           type. The list must not change across multiple\r
                           calls to the same driver. The first syntax\r
                           type in the list is the default type for the\r
                           driver.\r
\r
  @retval EFI_SUCCESS            The regular expression syntax types list\r
                                 was returned successfully.\r
  @retval EFI_UNSUPPORTED        The service is not supported by this driver.\r
  @retval EFI_DEVICE_ERROR       The list of syntax types could not be\r
                                 retrieved due to a hardware or firmware error.\r
  @retval EFI_BUFFER_TOO_SMALL   The buffer RegExSyntaxTypeList is too small\r
                                 to hold the result.\r
  @retval EFI_INVALID_PARAMETER  RegExSyntaxTypeListSize is NULL\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_REGULAR_EXPRESSION_GET_INFO) (\r
  IN     EFI_REGULAR_EXPRESSION_PROTOCOL *This,\r
  IN OUT UINTN                           *RegExSyntaxTypeListSize,\r
  OUT    EFI_REGEX_SYNTAX_TYPE           *RegExSyntaxTypeList\r
  );\r
\r
/**\r
  Checks if the input string matches to the regular expression pattern.\r
\r
  This          A pointer to the EFI_REGULAR_EXPRESSION_PROTOCOL instance.\r
                Type EFI_REGULAR_EXPRESSION_PROTOCOL is defined in Section\r
                XYZ.\r
\r
  String        A pointer to a NULL terminated string to match against the\r
                regular expression string specified by Pattern.\r
\r
  Pattern       A pointer to a NULL terminated string that represents the\r
                regular expression.\r
\r
  SyntaxType    A pointer to the EFI_REGEX_SYNTAX_TYPE that identifies the\r
                regular expression syntax type to use. May be NULL in which\r
                case the function will use its default regular expression\r
                syntax type.\r
\r
  Result        On return, points to TRUE if String fully matches against\r
                the regular expression Pattern using the regular expression\r
                SyntaxType. Otherwise, points to FALSE.\r
\r
  Captures      A Pointer to an array of EFI_REGEX_CAPTURE objects to receive\r
                the captured groups in the event of a match. The full\r
                sub-string match is put in Captures[0], and the results of N\r
                capturing groups are put in Captures[1:N]. If Captures is\r
                NULL, then this function doesn't allocate the memory for the\r
                array and does not build up the elements. It only returns the\r
                number of matching patterns in CapturesCount. If Captures is\r
                not NULL, this function returns a pointer to an array and\r
                builds up the elements in the array. CapturesCount is also\r
                updated to the number of matching patterns found. It is the\r
                caller's responsibility to free the memory pool in Captures\r
                and in each CapturePtr in the array elements.\r
\r
  CapturesCount On output, CapturesCount is the number of matching patterns\r
                found in String. Zero means no matching patterns were found\r
                in the string.\r
\r
  @retval EFI_SUCCESS            The regular expression string matching\r
                                 completed successfully.\r
  @retval EFI_UNSUPPORTED        The regular expression syntax specified by\r
                                 SyntaxTypeis not supported by this driver.\r
  @retval EFI_DEVICE_ERROR       The regular expression string matching\r
                                 failed due to a hardware or firmware error.\r
  @retval EFI_INVALID_PARAMETER  String, Pattern, Result, or CapturesCountis\r
                                 NULL.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_REGULAR_EXPRESSION_MATCH) (\r
  IN  EFI_REGULAR_EXPRESSION_PROTOCOL *This,\r
  IN  CHAR16                          *String,\r
  IN  CHAR16                          *Pattern,\r
  IN  EFI_REGEX_SYNTAX_TYPE           *SyntaxType, OPTIONAL\r
  OUT BOOLEAN                         *Result,\r
  OUT EFI_REGEX_CAPTURE               **Captures, OPTIONAL\r
  OUT UINTN                           *CapturesCount\r
  );\r
\r
struct _EFI_REGULAR_EXPRESSION_PROTOCOL {\r
  EFI_REGULAR_EXPRESSION_MATCH     MatchString;\r
  EFI_REGULAR_EXPRESSION_GET_INFO  GetInfo;\r
} ;\r
\r
extern EFI_GUID gEfiRegularExpressionProtocolGuid;\r
\r
//\r
// For regular expression rules specified in the POSIX Extended Regular\r
// Expression (ERE) Syntax:\r
//\r
extern EFI_GUID gEfiRegexSyntaxTypePosixExtendedGuid;\r
\r
//\r
// For regular expression rules specifiedin the ECMA 262 Specification\r
//\r
extern EFI_GUID gEfiRegexSyntaxTypeEcma262Guid;\r
\r
//\r
// For regular expression rules specified in the Perl standard:\r
//\r
extern EFI_GUID gEfiRegexSyntaxTypePerlGuid;\r
\r
#endif\r
Commit	Line	Data
6f7c885a ED	1	/** @file\r
	2	This section defines the Regular Expression Protocol. This protocol isused to match\r
	3	Unicode strings against Regular Expression patterns.\r
	4	\r
497a5fb1	5	Copyright (c) 2015-2018, Intel Corporation. All rights reserved.<BR>\r
6f7c885a ED	6	This program and the accompanying materials are licensed and made available under\r
	7	the terms and conditions of the BSD License that accompanies this distribution.\r
	8	The full text of the license may be found at\r
	9	http://opensource.org/licenses/bsd-license.php.\r
	10	\r
	11	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
	12	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
	13	\r
497a5fb1 SZ	14	@par Revision Reference:\r
	15	This Protocol was introduced in UEFI Specification 2.5.\r
	16	\r
6f7c885a ED	17	**/\r
	18	\r
	19	#ifndef __REGULAR_EXPRESSION_PROTOCOL_H__\r
	20	#define __REGULAR_EXPRESSION_PROTOCOL_H__\r
	21	\r
	22	#define EFI_REGULAR_EXPRESSION_PROTOCOL_GUID \\r
	23	{ \\r
	24	0xB3F79D9A, 0x436C, 0xDC11, {0xB0, 0x52, 0xCD, 0x85, 0xDF, 0x52, 0x4C, 0xE6 } \\r
	25	}\r
	26	\r
	27	#define EFI_REGEX_SYNTAX_TYPE_POSIX_EXTENDED_GUID \\r
	28	{ \\r
	29	0x5F05B20F, 0x4A56, 0xC231, {0xFA, 0x0B, 0xA7, 0xB1, 0xF1, 0x10, 0x04, 0x1D } \\r
	30	}\r
	31	\r
	32	#define EFI_REGEX_SYNTAX_TYPE_PERL_GUID \\r
	33	{ \\r
	34	0x63E60A51, 0x497D, 0xD427, {0xC4, 0xA5, 0xB8, 0xAB, 0xDC, 0x3A, 0xAE, 0xB6 } \\r
	35	}\r
	36	\r
	37	#define EFI_REGEX_SYNTAX_TYPE_ECMA_262_GUID \\r
	38	{ \\r
	39	0x9A473A4A, 0x4CEB, 0xB95A, {0x41, 0x5E, 0x5B, 0xA0, 0xBC, 0x63, 0x9B, 0x2E } \\r
	40	}\r
	41	\r
	42	typedef struct _EFI_REGULAR_EXPRESSION_PROTOCOL EFI_REGULAR_EXPRESSION_PROTOCOL;\r
	43	\r
	44	\r
	45	typedef struct {\r
	46	CONST CHAR16 *CapturePtr; // Pointer to the start of the captured sub-expression\r
	47	// within matched String.\r
	48	\r
	49	UINTN Length; // Length of captured sub-expression.\r
	50	} EFI_REGEX_CAPTURE;\r
	51	\r
	52	typedef EFI_GUID EFI_REGEX_SYNTAX_TYPE;\r
	53	\r
	54	//\r
	55	// Protocol member functions\r
	56	//\r
	57	/**\r
	58	Returns information about the regular expression syntax types supported\r
	59	by the implementation.\r
	60	\r
	61	This A pointer to the EFI_REGULAR_EXPRESSION_PROTOCOL\r
	62	instance.\r
	63	\r
	64	RegExSyntaxTypeListSize On input, the size in bytes of RegExSyntaxTypeList.\r
	65	On output with a return code of EFI_SUCCESS, the\r
	66	size in bytes of the data returned in\r
	67	RegExSyntaxTypeList. On output with a return code\r
	68	of EFI_BUFFER_TOO_SMALL, the size of\r
	69	RegExSyntaxTypeListrequired to obtain the list.\r
	70	\r
	71	RegExSyntaxTypeList A caller-allocated memory buffer filled by the\r
	72	driver with one EFI_REGEX_SYNTAX_TYPEelement\r
	73	for each supported Regular expression syntax\r
	74	type. The list must not change across multiple\r
	75	calls to the same driver. The first syntax\r
	76	type in the list is the default type for the\r
	77	driver.\r
	78	\r
	79	@retval EFI_SUCCESS The regular expression syntax types list\r
	80	was returned successfully.\r
81	@retval EFI_UNSUPPORTED The service is not supported by this driver.\r
82	@retval EFI_DEVICE_ERROR The list of syntax types could not be\r
83	retrieved due to a hardware or firmware error.\r
84	@retval EFI_BUFFER_TOO_SMALL The buffer RegExSyntaxTypeList is too small\r
85	to hold the result.\r
86	@retval EFI_INVALID_PARAMETER RegExSyntaxTypeListSize is NULL\r
87	\r
88	**/\r
89	typedef\r
90	EFI_STATUS\r
91	(EFIAPI *EFI_REGULAR_EXPRESSION_GET_INFO) (\r
92	IN EFI_REGULAR_EXPRESSION_PROTOCOL *This,\r
93	IN OUT UINTN *RegExSyntaxTypeListSize,\r
94	OUT EFI_REGEX_SYNTAX_TYPE *RegExSyntaxTypeList\r
95	);\r
96	\r
97	/**\r
98	Checks if the input string matches to the regular expression pattern.\r
99	\r
100	This A pointer to the EFI_REGULAR_EXPRESSION_PROTOCOL instance.\r
101	Type EFI_REGULAR_EXPRESSION_PROTOCOL is defined in Section\r
102	XYZ.\r
103	\r
104	String A pointer to a NULL terminated string to match against the\r
105	regular expression string specified by Pattern.\r
106	\r
107	Pattern A pointer to a NULL terminated string that represents the\r
108	regular expression.\r
109	\r
110	SyntaxType A pointer to the EFI_REGEX_SYNTAX_TYPE that identifies the\r
111	regular expression syntax type to use. May be NULL in which\r
112	case the function will use its default regular expression\r
113	syntax type.\r
114	\r
115	Result On return, points to TRUE if String fully matches against\r
116	the regular expression Pattern using the regular expression\r
117	SyntaxType. Otherwise, points to FALSE.\r
118	\r
119	Captures A Pointer to an array of EFI_REGEX_CAPTURE objects to receive\r
120	the captured groups in the event of a match. The full\r
121	sub-string match is put in Captures[0], and the results of N\r
122	capturing groups are put in Captures[1:N]. If Captures is\r
123	NULL, then this function doesn't allocate the memory for the\r
124	array and does not build up the elements. It only returns the\r
125	number of matching patterns in CapturesCount. If Captures is\r
126	not NULL, this function returns a pointer to an array and\r
127	builds up the elements in the array. CapturesCount is also\r
128	updated to the number of matching patterns found. It is the\r
129	caller's responsibility to free the memory pool in Captures\r
130	and in each CapturePtr in the array elements.\r
131	\r
132	CapturesCount On output, CapturesCount is the number of matching patterns\r
133	found in String. Zero means no matching patterns were found\r
134	in the string.\r
135	\r
136	@retval EFI_SUCCESS The regular expression string matching\r
137	completed successfully.\r
138	@retval EFI_UNSUPPORTED The regular expression syntax specified by\r
139	SyntaxTypeis not supported by this driver.\r
140	@retval EFI_DEVICE_ERROR The regular expression string matching\r
141	failed due to a hardware or firmware error.\r
142	@retval EFI_INVALID_PARAMETER String, Pattern, Result, or CapturesCountis\r
143	NULL.\r
144	\r
145	**/\r
146	typedef\r
147	EFI_STATUS\r
148	(EFIAPI *EFI_REGULAR_EXPRESSION_MATCH) (\r
149	IN EFI_REGULAR_EXPRESSION_PROTOCOL *This,\r
150	IN CHAR16 *String,\r
151	IN CHAR16 *Pattern,\r
152	IN EFI_REGEX_SYNTAX_TYPE *SyntaxType, OPTIONAL\r
153	OUT BOOLEAN *Result,\r
154	OUT EFI_REGEX_CAPTURE **Captures, OPTIONAL\r
155	OUT UINTN *CapturesCount\r
156	);\r
157	\r
158	struct _EFI_REGULAR_EXPRESSION_PROTOCOL {\r
159	EFI_REGULAR_EXPRESSION_MATCH MatchString;\r
160	EFI_REGULAR_EXPRESSION_GET_INFO GetInfo;\r
161	} ;\r
162	\r
163	extern EFI_GUID gEfiRegularExpressionProtocolGuid;\r
164	\r
165	//\r
166	// For regular expression rules specified in the POSIX Extended Regular\r
167	// Expression (ERE) Syntax:\r
168	//\r
169	extern EFI_GUID gEfiRegexSyntaxTypePosixExtendedGuid;\r
170	\r
171	//\r
172	// For regular expression rules specifiedin the ECMA 262 Specification\r
173	//\r
174	extern EFI_GUID gEfiRegexSyntaxTypeEcma262Guid;\r
175	\r
176	//\r
177	// For regular expression rules specified in the Perl standard:\r
178	//\r
179	extern EFI_GUID gEfiRegexSyntaxTypePerlGuid;\r
180	\r
181	#endif\r