SAL аннотации.

  • Article

? ????????? ????? ? ??????? ???????? Win32.Utf8 – ?? ?????? ?????, ??? ???, ??????? ?????, ?????? ?????? ?????????? ?? ???????. ??? ?? ?????, ?????? ?????????? ???????? ?, ?? ??????????? ????, ? ???????? ?? ??????? SAL ?????????.

???????? ???????? ??????????, ??????? ? ????????? – ??? ????????? sal.h ?? ???????? Visual C++. ? ??? ?????????? ?????????? ????????? ???????? ????, ??? ???????????? ??????????? ????? __deref_inout_ecount_part_opt. ????? ????, ??? ?? ?????????? ???????, ????????????? SAL ????????? ? ????? ???????? ??? ???????????? ??????????? PREfast. ?? ??? ?????????? ?????? ?????? ??? SAL ????????? «???????? ?? ????? ????».

??????????? ????????? ???? ? Platform SDK ??? Windows 2003 - specstrings .h . ? Windows SDK ??? Vista ??? ??? ????? ????????.

SAL ?????????? ????????? ?????? ??? ???????? ?????????? ??????? ? ?????? ????????. ?????? ???????? ???????/???? ????????? ??????? ?????????????? ????? ??? ??????????? ???????? «???????????»:

  • 0-?? ??????? ????????? ? ?????? ?????????, ?.?. ??????????????? ? ???????? ? ????? ??? ???????? ??????????;
  • 1-?? ??????? ????????? ? ???????? ??? ??????? ????????, ?? ??????? ????????? ???????? ???????. ?.?. ???????? ?????? ???? ??????????;
  • 2-?? ??????? ????????? ? ????????, ?? ??????? ????????? ?????????, ?? ??????? ????????? ???????? ???????. ????????, ??? 1-?? ??????? ????? ???? ???????? ????????, ?? 2-?? ??????? ????? ???? ??????????? ?????????? ????????/???????? ????????.
  • ? ?.?.

????????, ??? ????????? «LPSTR* arg» 0-?? ??????? ??? ??? arg (????????? ?? ?????????), 1-?? – ????????? ?? ??????, ?? ??????? ????????? arg ? 2-?? – ??? ???? ??????, ?????? ?????, ?????????? ??? ??????.

??? ??????? ?? ??????? ??????????? ????? ???? ?????? ????????? ?????????:

  • _in – ???????? ?????? ????????????? (valid) ????? ??????? ???????;
  • _out – ???????? ?????? ???? ????????????? ????? ?????? ???????;
  • _opt – ???????? ????? ???? ???????;
  • _ecount ??? _bcount – ????? ?????? ???????? ? ????????? ??? ??????;
  • _part – ?????? ??????????? ???? ???????? ??????????????????;
  • _z (??? _nz) – ?????????, ??? ????????? ?????????????????? ??????? ?????? ?????? ???? ??????? (??? ?? ??????).

?? ??? ????????? ????????? ?? ???? ???????. ????????, ??? 0-??? ?????? ????? ????? ?????? _in, _out ? _opt , ????????? ????? «??????» ?? ??????? ?????? ?????? ????????? ?????? ????????. ??????? ?????????? SAL ??????????? ??? ?????? ???????????. ? ???????, ??? ?? ???? ??????????? ????????? ????????? ???? «?????? ?????????? ?? ??????» ? ???????? ???????? ????????? ??????? ?????? 2-???. ?????????? SAL ????????? ??????? ?????? ???????? ???????????????? ?????????? ?????????? ? ??????????, ???????, ??? ?? ?????, ????????? ??????? 99% ???????, ????????????? ? ???????? ?????.

? ?????? ????? ?????????????? ????? ?????????? ? ??????????????? SAL ?????????. ??? ????? ???????????? ????????? ??????? (?? sal.h):

Level

Usage

Size

Output

Null-terminated

Optional

Parameters
- - - - - - -
_deref _in _ecount _full _z _opt (size)
_deref_opt _out _bcount _part _nz   (size, length)
  _inout          

??????? ????????? ? ??????? ????????? ? ???, ??? ???????? ?????? ??????????? ? ?????????.

Level: ???????? ?????? ??????? ?????????? ?????? ?????????:

  • ???? ??????? ?? ??????, ?? SAL ????????? ?????????? ??? ???????? ?, ???? ??? ?????????, - ?????, ?? ??????? ?? ?????????. (??????? 0 ? 1);
  • “_deref” ?????????, ??? ??????????? ???????? – ??? ????????? ?? ????????? ?? ????? (?????? 0, 1 ? 2). ??? ???? ???????????????, ??? ?????? ?????? ?? ?????? 1 – ???? ???????;
  • “_deref_opt” ????????????? ?????????, ??? ????????? ?? ?????? 1 ????? ???? ???????.

Usage: ?????????, ??? ???????? ?????? ???? ???????????? ??/????? ?????? ???????.

Size: ?????????? ?????? ?????? ?? ??????, ????????? ? ??????? “_deref”. ?????? ??????????? ? ??????? ????? SAL ?????????. “_ecount”/”_bcount” ???????? ??????? ????????? ????? ??????: ????????/?????.

Output: ????????? ????????? ?? ?? ????? ????????????????????? ?????.

  • ??-?????????, ????????? ??????????????????? ?????? ????? ?????? ?????????? ??? ??????. ????? ?????? ????? ????????? ?????;
  • “_full” ??????? ? ???, ??? ????? ?????? ???? ?????????????????? ?? ?????, ???????? ??????;
  • “_part” ????????? ???? ???????? ????? ????????????????????? ????? ??????.

Null-terminated: ???? ?????????, ??? ?????? ??????????? ??????? ?????????.

Optional: ??????? “_opt” ??????? ? ???, ??? ???????? ??????? ????? ???? ???????. ? ??????? ?? “_deref_opt”, “_opt” ????????? ? 0-? ?????? ???????????. ??? ????????? ????????????? “_deref_opt” ? “_opt”, ????????, ??? ??? ????????? ????? ???? ????????.

Parameters: ????????? ?????? ????? ?????? ? ????? ??? ?????????????????? ?????.

?????:

  • “_deref”, “_deref_opt” ? “_opt” – ???????? ?????? ??????????? ?????????;
  • “_in”, “_out” ? “_inout” – ?????????? ????? ????? ????????? ?? ???? ???????;
  • “_bcount”, “_ecount”, “_full”, “_part”, “_z” ? “_nz” – ????????? ?????????????? ?????? ??????.

??????: ???????? ???? «LPSTR* Arg», ??????? ???????????? ??? ????????? ?????? ?? ??????? ????? ???? ?????? ????????? ???????:

 __deref_out_z LPSTR* Arg;

????? ?????????? ????????, ??? ?? ?????????? ??????? ????????? ?? ??????? ????????? Arg ????? ?????????????????? ?????????? ?? ??????, ????????????? ?????. ???????? ????????, ??? ??? ???? ????? ??? ???????? Arg ?????? ???? ?????????????? ????????? ?????????? ?? ????? ?????? ???????, ?.?. Arg ?????? ???? ?????? ??? “_in” ???????? ?? ??????? ? ?????? ??????? ???????????, ?????? ??????? ????? “_in” ? ??????? ???. ??????? ? ???, ??? ???? _in ?????? ??????????????? ??? ???????? “_deref”, ????? ????????? ????????????? ?? ????? ????.

?????? ????????? ?????, ??????? ??????????, - ??? ??????????? ????????? (????????????? “_in”) ? ??????? ?????????????? SAL ????????? ?????????? ???????, ????? ? ?????? ????????. ?? ?? ???? ? ????????? ???.

Cross-posted from blog.not-a-kernel-guy.com.