(SST) ShlWAPI.pas Version 1.08

Developer Reference
(SST)ShlWAPI StrStrNIW Function
Searches the specified number of characters in a string for a substring, ignoring the character case.
Scope
Global (i.e. this function can be called/accessed from code in any unit that includes/uses (SST)ShlWAPI.pas).
Syntax
function StrStrNIW(lpFirst : LPCWSTR; lpSrch : LPCWSTR; cchMax : UINT) : LPCWSTR;  
Parameters
lpFirst [in] Pointer to, or address of, the null-terminated, Unicode string in which to search.
lpSrch [in] Pointer to, or address of, the null-terminated, Unicode (sub-)string to find/locate.
cchMax [in] The maximum number of characters (counted from the beginning of the string being searched) in which to search for an occurrence of the string specified in the lpSrch parameter.
Return Values
If the function succeeds in locating the substring within the specified number of characters of the string being searched, it returns a pointer to the beginning of the substring within the searched string. If the function fails for any reason, it returns NIL.
Remarks
The search is not case sensitive. In other words, searching for any combination of upper and lower case characters that form the word to search for, will produce the same result.
This function is only exported in a Unicode and not, like most other ShlWAPI.dll functions, in both an ANSI and a Unicode version.
Although the function is exported by name as of ShlWAPI.dll version 6.0 under Windows 2000 and, possibly, earlier Windows versions with IE 6.0, it is erroneously documented as being exported by Shell32.dll and requiring Windows Vista. Furthermore, the first declaration of the function prototype in ShlWAPI.h is enclosed in a compiler directive that uses an undeclared constant ("_WIN32_IE_IE6").
To import and call the function when using the SST implementation of the ShlWAPI.pas unit, it is necessary to specify "SST_SHLWAPIVER6PT0", either in the source code or in the project settings. In the example below, the required compiler directive was specified in the first line of the source code.
Example
{$DEFINE SST_SHLWAPIVER6PT0} {$IFDEF SST_SHLWAPIVER6PT0} PROCEDURE TForm4.TestShlWAPIStrStrNIW(Sender : TObject); VAR strtosrchfor : WideString; VAR txttosearch : WideString; VAR uptocharnum : UINT; VAR apiretptr : POINTER; VAR newinfoline : STRING; BEGIN strtosrchfor := ''; txttosearch := ''; uptocharnum := 0; apiretptr := NIL; newinfoline := ''; strtosrchfor := 'FoX'; uptocharnum := 16; txttosearch := 'The quick, brown fox jumped over the fence and hid in the fox burrow'; newinfoline := 'StrStrNIW called with lpFirst (without the quotation marks) = "' + txttosearch + '", lpSrch = ' + strtosrchfor + ', and cchMax = ' + IntToStr(uptocharnum); Memo1.Lines.Add(newinfoline); apiretptr := StrStrNIW(PWChar(txttosearch), PWChar(strtosrchfor), uptocharnum); IF apiretptr <> NIL THEN newinfoline := 'StrStrNIW returned a pointer to "' + PWChar(apiretptr) + '"' ELSE newinfoline := 'StrStrNIW returned NIL !'; Memo1.Lines.Add(newinfoline); strtosrchfor := 'FENCE'; uptocharnum := 42; txttosearch := 'The quick, brown fox jumped over the fence and hid in the fox burrow'; newinfoline := 'StrStrNIW called with lpFirst (without the quotation marks) = "' + txttosearch + '", lpSrch = ' + strtosrchfor + ', and cchMax = ' + IntToStr(uptocharnum); Memo1.Lines.Add(newinfoline); apiretptr := StrStrNIW(PWChar(txttosearch), PWChar(strtosrchfor), uptocharnum); IF apiretptr <> NIL THEN newinfoline := 'StrStrNIW returned a pointer to "' + PWChar(apiretptr) + '"' ELSE newinfoline := 'StrStrNIW returned NIL !'; Memo1.Lines.Add(newinfoline); txttosearch := 'The quick, brown fox jumped over the fence and hid in the fox burrow'; strtosrchfor := 'fox'; uptocharnum := Length(txttosearch); // = is the length of the string being searched newinfoline := 'StrStrNIW called with lpFirst (without the quotation marks) = "' + txttosearch + '", lpSrch = ' + strtosrchfor + ', and cchMax = ' + IntToStr(uptocharnum); Memo1.Lines.Add(newinfoline); apiretptr := StrStrNIW(PWChar(txttosearch), PWChar(strtosrchfor), uptocharnum); IF apiretptr <> NIL THEN newinfoline := 'StrStrNIW returned a pointer to "' + PWChar(apiretptr) + '"' ELSE newinfoline := 'StrStrNIW returned NIL !'; Memo1.Lines.Add(newinfoline); txttosearch := 'The quick, brown fox jumped over the fence and hid in the fox burrow'; strtosrchfor := 'T'; uptocharnum := 1; newinfoline := 'StrStrNIW called with lpFirst (without the quotation marks) = "' + txttosearch + '", lpSrch = ' + strtosrchfor + ', and cchMax = ' + IntToStr(uptocharnum); Memo1.Lines.Add(newinfoline); apiretptr := StrStrNIW(PWChar(txttosearch), PWChar(strtosrchfor), uptocharnum); IF apiretptr <> NIL THEN newinfoline := 'StrStrNIW returned a pointer to "' + PWChar(apiretptr) + '"' ELSE newinfoline := 'StrStrNIW returned NIL !'; Memo1.Lines.Add(newinfoline); txttosearch := 'The quick, brown fox jumped over the fence and hid in the fox burrow'; strtosrchfor := 'T'; uptocharnum := 0; newinfoline := 'StrStrNIW called with lpFirst (without the quotation marks) = "' + txttosearch + '", lpSrch = ' + strtosrchfor + ', and cchMax = ' + IntToStr(uptocharnum); Memo1.Lines.Add(newinfoline); apiretptr := StrStrNIW(PWChar(txttosearch), PWChar(strtosrchfor), uptocharnum); IF apiretptr <> NIL THEN newinfoline := 'StrStrNIW returned a pointer to "' + PWChar(apiretptr) + '"' ELSE newinfoline := 'StrStrNIW returned NIL !'; Memo1.Lines.Add(newinfoline); Memo1.Lines.Add(''); END; {$ENDIF}
The above example code produces the following output:
StrStrNIW called with lpFirst (without the quotation marks) = "The quick, brown fox jumped over the fence and hid in the fox burrow", lpSrch = FoX, and cchMax = 16 StrStrNIW returned NIL ! StrStrNIW called with lpFirst (without the quotation marks) = "The quick, brown fox jumped over the fence and hid in the fox burrow", lpSrch = FENCE, and cchMax = 42 StrStrNIW returned a pointer to "fence and hid in the fox burrow" StrStrNIW called with lpFirst (without the quotation marks) = "The quick, brown fox jumped over the fence and hid in the fox burrow", l pSrch = fox, and cchMax = 68 StrStrNIW returned a pointer to "fox jumped over the fence and hid in the fox burrow" StrStrNIW called with lpFirst (without the quotation marks) = "The quick, brown fox jumped over the fence and hid in the fox burrow", lpSrch = T, and cchMax = 1 StrStrNIW returned a pointer to "The quick, brown fox jumped over the fence and hid in the fox burrow" StrStrNIW called with lpFirst (without the quotation marks) = "The quick, brown fox jumped over the fence and hid in the fox burrow", lpSrch = T, and cchMax = 0 StrStrNIW returned NIL !
Requirements
Unit: Declared and imported in (SST)ShlWAPI.pas
Library: (SST)ShlWAPI.dcu/(SST)ShlWAPI.obj
Unicode: Implemented as Unicode (StrStrNIW) function only.
Min. ShlWAPI.dll version according to MS SDK doc.: undocumented
Min. ShlWAPI.dll version based on SST research: 6.0
Min. OS version(s) according to Microsoft SDK doc.: Windows Vista
Min. OS version(s) according to SST research.: Windows 2000 with IE 6
See Also
StrStrNW, StrStrI, StrStr, StrCSpn, StrCSpnI.
 
Windows APIs: StrStrNIW, StrStrNW, StrStrI, StrStr, StrCSpn, StrCSpnI.


Document/Contents version 1.00
Page/URI last updated on 07.12.2023
 
Copyright © Stoelzel Software Technologie (SST) 2010 - 2015
Suggestions and comments mail to:
webmaster@stoelzelsoftwaretech.com