MdeModulePkg/Universal/RegularExpressionDxe/RegularExpressionDxe.h

   1 /** @file
   2   EFI_REGULAR_EXPRESSION_PROTOCOL Header File.
   3
   4   (C) Copyright 2015 Hewlett Packard Enterprise Development LP<BR>
   5
   6   This program and the accompanying materials are licensed and made available
   7   under the terms and conditions of the BSD License that accompanies this
   8   distribution.  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, WITHOUT
  12   WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16 #ifndef __REGULAR_EXPRESSIONDXE_H__
  17 #define __REGULAR_EXPRESSIONDXE_H__
  18
  19 #include "Oniguruma/oniguruma.h"
  20
  21 #include <Uefi.h>
  22 #include <Protocol/RegularExpressionProtocol.h>
  23 #include <Library/UefiBootServicesTableLib.h>
  24 #include <Library/BaseMemoryLib.h>
  25 #include <Library/MemoryAllocationLib.h>
  26 #include <Library/DebugLib.h>
  27 #include <Library/BaseLib.h>
  28
  29 #define ARRAY_SIZE(Array) (sizeof(Array) / sizeof(*Array))
  30
  31 /**
  32   Checks if the input string matches to the regular expression pattern.
  33
  34   @param This          A pointer to the EFI_REGULAR_EXPRESSION_PROTOCOL instance.
  35                        Type EFI_REGULAR_EXPRESSION_PROTOCOL is defined in Section
  36                        XYZ.
  37
  38   @param String        A pointer to a NULL terminated string to match against the
  39                        regular expression string specified by Pattern.
  40
  41   @param Pattern       A pointer to a NULL terminated string that represents the
  42                        regular expression.
  43
  44   @param SyntaxType    A pointer to the EFI_REGEX_SYNTAX_TYPE that identifies the
  45                        regular expression syntax type to use. May be NULL in which
  46                        case the function will use its default regular expression
  47                        syntax type.
  48
  49   @param Result        On return, points to TRUE if String fully matches against
  50                        the regular expression Pattern using the regular expression
  51                        SyntaxType. Otherwise, points to FALSE.
  52
  53   @param Captures      A Pointer to an array of EFI_REGEX_CAPTURE objects to receive
  54                        the captured groups in the event of a match. The full
  55                        sub-string match is put in Captures[0], and the results of N
  56                        capturing groups are put in Captures[1:N]. If Captures is
  57                        NULL, then this function doesn't allocate the memory for the
  58                        array and does not build up the elements. It only returns the
  59                        number of matching patterns in CapturesCount. If Captures is
  60                        not NULL, this function returns a pointer to an array and
  61                        builds up the elements in the array. CapturesCount is also
  62                        updated to the number of matching patterns found. It is the
  63                        caller's responsibility to free the memory pool in Captures
  64                        and in each CapturePtr in the array elements.
  65
  66   @param CapturesCount On output, CapturesCount is the number of matching patterns
  67                 found in String. Zero means no matching patterns were found
  68                 in the string.
  69
  70   @retval EFI_SUCCESS            The regular expression string matching
  71                                  completed successfully.
  72   @retval EFI_UNSUPPORTED        The regular expression syntax specified by
  73                                  SyntaxType is not supported by this driver.
  74   @retval EFI_DEVICE_ERROR       The regular expression string matching
  75                                  failed due to a hardware or firmware error.
  76   @retval EFI_INVALID_PARAMETER  String, Pattern, Result, or CapturesCountis
  77                                  NULL.
  78
  79 **/
  80 EFI_STATUS
  81 EFIAPI
  82 RegularExpressionMatch (
  83   IN  EFI_REGULAR_EXPRESSION_PROTOCOL *This,
  84   IN  CHAR16                          *String,
  85   IN  CHAR16                          *Pattern,
  86   IN  EFI_REGEX_SYNTAX_TYPE           *SyntaxType, OPTIONAL
  87   OUT BOOLEAN                         *Result,
  88   OUT EFI_REGEX_CAPTURE               **Captures, OPTIONAL
  89   OUT UINTN                           *CapturesCount
  90   );
  91
  92 /**
  93   Returns information about the regular expression syntax types supported
  94   by the implementation.
  95
  96   @param This                     A pointer to the EFI_REGULAR_EXPRESSION_PROTOCOL
  97                                   instance.
  98
  99   @param RegExSyntaxTypeListSize  On input, the size in bytes of RegExSyntaxTypeList.
 100                                   On output with a return code of EFI_SUCCESS, the
 101                                   size in bytes of the data returned in
 102                                   RegExSyntaxTypeList. On output with a return code
 103                                   of EFI_BUFFER_TOO_SMALL, the size of
 104                                   RegExSyntaxTypeList required to obtain the list.
 105
 106   @param RegExSyntaxTypeList      A caller-allocated memory buffer filled by the
 107                                   driver with one EFI_REGEX_SYNTAX_TYPE element
 108                                   for each supported Regular expression syntax
 109                                   type. The list must not change across multiple
 110                                   calls to the same driver. The first syntax
 111                                   type in the list is the default type for the
 112                                   driver.
 113
 114   @retval EFI_SUCCESS            The regular expression syntax types list
 115                                  was returned successfully.
 116   @retval EFI_UNSUPPORTED        The service is not supported by this driver.
 117   @retval EFI_DEVICE_ERROR       The list of syntax types could not be
 118                                  retrieved due to a hardware or firmware error.
 119   @retval EFI_BUFFER_TOO_SMALL   The buffer RegExSyntaxTypeList is too small
 120                                  to hold the result.
 121   @retval EFI_INVALID_PARAMETER  RegExSyntaxTypeListSize is NULL
 122
 123 **/
 124 EFI_STATUS
 125 EFIAPI
 126 RegularExpressionGetInfo (
 127   IN     EFI_REGULAR_EXPRESSION_PROTOCOL *This,
 128   IN OUT UINTN                           *RegExSyntaxTypeListSize,
 129   OUT    EFI_REGEX_SYNTAX_TYPE           *RegExSyntaxTypeList
 130   );
 131
 132 #endif