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