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