From 923e8f113ef8226178f2112b2f24f6e85ed3634e Mon Sep 17 00:00:00 2001 From: Mustafa Mohamad Date: Thu, 23 Jul 2020 00:55:26 -0400 Subject: [PATCH] initial commit --- .appveyor.yml | 31 ++++ .github/workflows/ci.yml | 22 +++ .travis.yml | 21 +++ README.md | 52 ++++++ _git2_a16356 | 1 - docs/Project.toml | 3 + docs/make.jl | 21 +++ docs/src/index.md | 152 ++++++++++++++++++ src/WinTypes.jl | 331 ++++++++++++++++++++++++++++++++++++++- 9 files changed, 632 insertions(+), 2 deletions(-) create mode 100644 .appveyor.yml create mode 100644 .github/workflows/ci.yml create mode 100644 .travis.yml delete mode 120000 _git2_a16356 create mode 100644 docs/Project.toml create mode 100644 docs/make.jl create mode 100644 docs/src/index.md diff --git a/.appveyor.yml b/.appveyor.yml new file mode 100644 index 0000000..1d36e0c --- /dev/null +++ b/.appveyor.yml @@ -0,0 +1,31 @@ +# Documentation: https://github.com/JuliaCI/Appveyor.jl +environment: + matrix: + - julia_version: 1.0 + - julia_version: 1.5 + - julia_version: nightly +platform: + - x64 + - x86 +cache: + - '%USERPROFILE%\.julia\artifacts' +matrix: + allow_failures: + - julia_version: nightly +branches: + only: + - master + - /release-.*/ +notifications: + - provider: Email + on_build_success: false + on_build_failure: false + on_build_status_changed: false +install: + - ps: iex ((new-object net.webclient).DownloadString("https://raw.githubusercontent.com/JuliaCI/Appveyor.jl/version-1/bin/install.ps1")) +build_script: + - echo "%JL_BUILD_SCRIPT%" + - C:\julia\bin\julia -e "%JL_BUILD_SCRIPT%" +test_script: + - echo "%JL_TEST_SCRIPT%" + - C:\julia\bin\julia -e "%JL_TEST_SCRIPT%" diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..4ecb1cf --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,22 @@ +name: Documentation +on: + - push + - pull_request +jobs: + docs: + name: Documentation + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: julia-actions/setup-julia@v1 + with: + version: '1' + - run: | + julia --project=docs -e ' + using Pkg + Pkg.develop(PackageSpec(path=pwd())) + Pkg.instantiate()' + - run: julia --project=docs docs/make.jl + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000..f3bd2ac --- /dev/null +++ b/.travis.yml @@ -0,0 +1,21 @@ +# Documentation: http://docs.travis-ci.com/user/languages/julia +language: julia +notifications: + email: false +julia: + - 1.0 + - 1.5 + - nightly +os: + - linux + - osx + - windows +arch: + - x64 +cache: + directories: + - ~/.julia/artifacts +jobs: + fast_finish: true + allow_failures: + - julia: nightly diff --git a/README.md b/README.md index ffab8e5..f2aef8e 100644 --- a/README.md +++ b/README.md @@ -1 +1,53 @@ # WinTypes + +This package defines aliases to [Windows Data types](https://docs.microsoft.com/en-us/windows/win32/winprog/windows-data-types). + + +## Why? + +This makes it easier to translate Windows function from MSDN documentation and +increases readability. + +Here's an example comparing calling Windows API functions with and without `WinTypes`: + +With `WinTypes` a Windows API call would look something like: +```julia +using WinTypes: HANDLE, DWORD, BOOL + +function get_console_mode() + STD_OUTPUT_HANDLE = -11 + hOutput = ccall(:GetStdHandle, stdcall, HANDLE, (DWORD,), STD_OUTPUT_HANDLE % DWORD) + dwMode = Ref{DWORD}() + ccall(:GetConsoleMode, stdcall, BOOL, (HANDLE, Ref{DWORD}), hOutput, dwMode) + return dwMode[] +end +``` +Now, compare this to the call without this package: +```julia + +function get_console_mode() + STD_OUTPUT_HANDLE = -11 + hOutput = ccall(:GetStdHandle, stdcall, Ptr{Cvoid}, (UInt32,), STD_OUTPUT_HANDLE % UInt32) + dwMode = Ref{UInt32}() + ccall(:GetConsoleMode, stdcall, Int32, (Ref{Cvoid}, Ref{UInt32}), hOutput, dwMode) + return dwMode[] +end +``` + +Finally, here are the corresponding Windows API function syntax definitions in `C`: + +``` +HANDLE WINAPI GetStdHandle( + _In_ DWORD nStdHandle +); +``` + +``` +BOOL WINAPI GetConsoleMode( + _In_ HANDLE hConsoleHandle, + _Out_ LPDWORD lpMode +); +``` + +As you can see, the call to these APIs using `WinTypes` is easier to translate and +directly translatable without manually looking up the myriad Windows data types. diff --git a/_git2_a16356 b/_git2_a16356 deleted file mode 120000 index 9a2c773..0000000 --- a/_git2_a16356 +++ /dev/null @@ -1 +0,0 @@ -testing \ No newline at end of file diff --git a/docs/Project.toml b/docs/Project.toml new file mode 100644 index 0000000..d57915a --- /dev/null +++ b/docs/Project.toml @@ -0,0 +1,3 @@ +[deps] +Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" +WinTypes = "7ce832dc-6953-4c0f-9163-51fbd0dcbc24" diff --git a/docs/make.jl b/docs/make.jl new file mode 100644 index 0000000..2faf25b --- /dev/null +++ b/docs/make.jl @@ -0,0 +1,21 @@ +using WinTypes +using Documenter + +makedocs(; + modules=[WinTypes], + authors="Mustafa Mohamad and contributors", + repo="https://github.com/musm/WinTypes.jl/blob/{commit}{path}#L{line}", + sitename="WinTypes.jl", + format=Documenter.HTML(; + prettyurls=get(ENV, "CI", "false") == "true", + canonical="https://musm.github.io/WinTypes.jl", + assets=String[], + ), + pages=[ + "Home" => "index.md", + ], +) + +deploydocs(; + repo="github.com/musm/WinTypes.jl.git", +) diff --git a/docs/src/index.md b/docs/src/index.md new file mode 100644 index 0000000..1314890 --- /dev/null +++ b/docs/src/index.md @@ -0,0 +1,152 @@ +```@meta +CurrentModule = WinTypes +``` + +# WinTypes + +## Usage + +First install the package: +```julia +]add WinTypes +``` + +Here's an example comparing calling Windows API functions with and without `WinTypes`: + +With `WinTypes` a Windows API call would look something like: +```julia +using WinTypes: HANDLE, DWORD, BOOL + +function get_console_mode() + STD_OUTPUT_HANDLE = -11 + hOutput = ccall(:GetStdHandle, stdcall, HANDLE, (DWORD,), STD_OUTPUT_HANDLE % DWORD) + dwMode = Ref{DWORD}() + ccall(:GetConsoleMode, stdcall, BOOL, (HANDLE, Ref{DWORD}), hOutput, dwMode) + return dwMode[] +end +``` +Now, compare this to the call without this package: +```julia + +function get_console_mode() + STD_OUTPUT_HANDLE = -11 + hOutput = ccall(:GetStdHandle, stdcall, Ptr{Cvoid}, (UInt32,), STD_OUTPUT_HANDLE % UInt32) + dwMode = Ref{UInt32}() + ccall(:GetConsoleMode, stdcall, Int32, (Ref{Cvoid}, Ref{UInt32}), hOutput, dwMode) + return dwMode[] +end +``` + +Finally, here are the corresponding Windows API function syntax definitions in `C`: + +``` +HANDLE WINAPI GetStdHandle( + _In_ DWORD nStdHandle +); +``` + +``` +BOOL WINAPI GetConsoleMode( + _In_ HANDLE hConsoleHandle, + _Out_ LPDWORD lpMode +); +``` + +As you can see, the call to these APIs using `WinTypes` is easier to translate and +directly translatable without manually looking up the myriad Windows data types. + + +## Alias List + +The following aliases are defined: +``` +FALSE = Cint(0) +TRUE = Cint(1) + +BOOL = Cint +BOOLEAN = BYTE +BYTE = Cuchar +CCHAR = Cchar +CHAR = Cchar +COLORREF = DWORD +DWORD = Culong +DWORDLONG = UInt64 +DWORD32 = UInt32 +DWORD64 = UInt64 +FLOAT = Cfloat +HACCEL = HANDLE +HANDLE = Ptr{Cvoid} +HBITMAP = HANDLE +HBRUSH = HANDLE +HCOLORSPACE = HANDLE +HCONV = HANDLE +HCONVLIST = HANDLE +HCURSOR = HICON +HDC = HANDLE +HDDEDATA = HANDLE +HDESK = HANDLE +HDROP = HANDLE +HDWP = HANDLE +HENHMETAFILE = HANDLE +HFILE = Cint +HFONT = HANDLE +HGDIOBJ = HANDLE +HGLOBAL = HANDLE +HHOOK = HANDLE +HICON = HANDLE +HINSTANCE = HANDLE +HKEY = HANDLE +HKL = HANDLE +HLOCAL = HANDLE +HMENU = HANDLE +HMETAFILE = HANDLE +HMODULE = HANDLE +HMONITOR = HANDLE +HPALETTE = HANDLE +HPEN = HANDLE +HRESULT = Clong +HRGN = HANDLE +HRSRC = HANDLE +HSZ = HANDLE +HWINSTA = HANDLE +HWND = HANDLE +INT = Cint +PHANDLE = Ptr{HANDLE} +PVOID = Ptr{Cvoid} +LPVOID = Ptr{Cvoid} +SHORT = Cshort +UCHAR = Cuchar +USHORT = Cushort +VOID = Cvoid +WCHAR = Cwchar_t +WORD = Cushort +PWCHAR = Ptr{WCHAR} +PWORD = Ptr{WORD} +LPWORD = Ptr{WORD} +PDWORD = Ptr{DWORD} +LPDWORD = Ptr{DWORD} + +PSTR = Ptr{CHAR} # char* +LPSTR = Ptr{CHAR} # char* + +PCSTR = Ptr{CHAR} # char* +LPCSTR = Ptr{CHAR} # char* + +PWSTR = Ptr{WCHAR} # wchar_t* +LPWSTR = Ptr{WCHAR} # wchar_t* + +PCWSTR = Ptr{WCHAR} # wchar_t* +LPCWSTR = Ptr{WCHAR} # const wchar_t* +``` + + +# Detailed References + +Below we include detailed documentation for some of the aliases defined in this package. +We refer to +[https://docs.microsoft.com/en-us/windows/win32/winprog/windows-data-types](https://docs.microsoft.com/en-us/windows/win32/winprog/windows-data-types) +for those not included below. + +```@autodocs +Modules = [WinTypes] +``` diff --git a/src/WinTypes.jl b/src/WinTypes.jl index 22eea9f..ed4a82e 100644 --- a/src/WinTypes.jl +++ b/src/WinTypes.jl @@ -1,5 +1,334 @@ module WinTypes -# Write your package code here. +# References: +# https://docs.microsoft.com/en-us/windows/win32/winprog/windows-data-types +# https://docs.microsoft.com/en-us/windows/win32/learnwin32/windows-coding-conventions?redirectedfrom=MSDN + +const FALSE = Cint(0) +const TRUE = Cint(1) + +const BOOL = Cint +# const BOOLEAN = BYTE +const BYTE = Cuchar +const BOOLEAN = BYTE +const CCHAR = Cchar +const CHAR = Cchar +# const COLORREF = DWORD +const DWORD = Culong +const COLORREF = DWORD +const DWORDLONG = UInt64 +const DWORD32 = UInt32 +const DWORD64 = UInt64 +const FLOAT = Cfloat +# const HACCEL = HANDLE +const HANDLE = Ptr{Cvoid} +const HACCEL = HANDLE +const HBITMAP = HANDLE +const HBRUSH = HANDLE +const HCOLORSPACE = HANDLE +const HCONV = HANDLE +const HCONVLIST = HANDLE +# const HCURSOR = HICON +const HDC = HANDLE +const HDDEDATA = HANDLE +const HDESK = HANDLE +const HDROP = HANDLE +const HDWP = HANDLE +const HENHMETAFILE = HANDLE +const HFILE = Cint +const HFONT = HANDLE +const HGDIOBJ = HANDLE +const HGLOBAL = HANDLE +const HHOOK = HANDLE +const HICON = HANDLE +const HCURSOR = HICON +const HINSTANCE = HANDLE +const HKEY = HANDLE +const HKL = HANDLE +const HLOCAL = HANDLE +const HMENU = HANDLE +const HMETAFILE = HANDLE +const HMODULE = HANDLE +const HMONITOR = HANDLE +const HPALETTE = HANDLE +const HPEN = HANDLE +const HRESULT = Clong +const HRGN = HANDLE +const HRSRC = HANDLE +const HSZ = HANDLE +const HWINSTA = HANDLE +const HWND = HANDLE +const INT = Cint +const PHANDLE = Ptr{HANDLE} +const PVOID = Ptr{Cvoid} +const LPVOID = Ptr{Cvoid} +const SHORT = Cshort +const UCHAR = Cuchar +const USHORT = Cushort +const VOID = Cvoid +const WCHAR = Cwchar_t +const WORD = Cushort +const PWCHAR = Ptr{WCHAR} +const PWORD = Ptr{WORD} +const LPWORD = Ptr{WORD} +const PDWORD = Ptr{DWORD} +const LPDWORD = Ptr{DWORD} + +const PSTR = Ptr{CHAR} # char* +const LPSTR = Ptr{CHAR} # char* + +const PCSTR = Ptr{CHAR} # const char* +const LPCSTR = Ptr{CHAR} # const char* + +const PWSTR = Ptr{WCHAR} # wchar_t* +const LPWSTR = Ptr{WCHAR} # wchar_t* + +const PCWSTR = Ptr{WCHAR} # const wchar_t* +const LPCWSTR = Ptr{WCHAR} # const wchar_t* + + +""" + const BOOL = Cint + +A Boolean variable (should be TRUE or FALSE). + +This type is declared in `WinDef.h` as follows: + +`typedef int BOOL;` + +BOOL is a typedef for an integer value that is used in a Boolean context. The header file +`WinDef.h` also defines two values for use with BOOL. + +``` +#define FALSE 0 +#define TRUE 1 +``` + +See also: [`TRUE`](@ref) and [`FALSE`](@ref) + +""" +BOOL + + +""" + const FALSE = Cint(0) + +A Boolean variable denoting FALSE. +""" +FALSE + + +""" + const TRUE = Cint(1) + +A Boolean variable denoting FALSE. Should only be used in specialized contexts since most functions +that reutnr a `BOOL` type can return any non-zero value to indicate Boolean truth. +""" +TRUE + +""" + const BYTE = Cuchar + +A byte (8 bits). + +This type is declared in `WinDef.h` as follows: + +`typedef unsigned char BYTE;` +""" +BYTE + +""" + const BOOLEAN = BYTE + +A Boolean variable (should be TRUE or FALSE). + +This type is declared in `WinNT.h` as follows: + +`typedef BYTE BOOLEAN;` +""" +BOOLEAN + +""" + const CCHAR = Cchar + +An 8-bit Windows (ANSI) character. + +This type is declared in `WinNT.h` as follows: + +`typedef char CCHAR;` +""" +CCHAR + +""" + const CCHAR = Cchar + +An 8-bit Windows (ANSI) character. + +This type is declared in `WinNT.h` as follows: + +`typedef char CHAR;` +""" +CHAR + +""" + const DWORD = Culong + +A 32-bit unsigned integer. + +This type is declared in `IntSafe.h` as follows: + +`typedef unsigned long DWORD;` +""" +DWORD + +""" + const DWORDLONG = UInt64 + +A 64-bit unsigned integer. + +This type is declared in `IntSafe.h` as follows: + +`typedef unsigned __int64 DWORDLONG;` +""" +DWORDLONG + +""" + const DWORD32 = UInt32 + +A 32-bit unsigned integer. + +This type is declared in `BaseTsd.h` as follows: + +`typedef unsigned int DWORD32;` +""" +DWORD32 + +""" + const DWORD64 = UInt64 + +A 64-bit unsigned integer. + +This type is declared in `IntSafe.h` as follows: + +`typedef unsigned __int64 DWORD64;` +""" +DWORD64 + +""" + const FLOAT = Cfloat + +A floating-point variable. + +This type is declared in `WinDef.h` as follows: + +`typedef float FLOAT;` +""" +FLOAT + +""" + const HANDLE = Ptr{Cvoid} + +A handle to an object. + +This type is declared in `WinNT.h` as follows: + +`typedef PVOID HANDLE;` +""" +HANDLE + + + + +""" + const HKEY = HANDLE + +A handle to a registry key. + +This type is declared in `WinDef.h` as follows: + +`typedef HANDLE HKEY;` +""" +HKEY + +""" + cosnt PVOID = Ptr{Cvoid} + +A pointer to any type. + +This type is declared in `WinNT.h` as follows: + +`typedef void *PVOID;` +""" +PVOID + +""" + const SHORT = Cshort + +A 16-bit integer. + +This type is declared in `WinNT.h` as follows: + +`typedef short SHORT;` +""" +SHORT + + +""" + const UCHAR = Cuchar + +An unsigned CHAR. + +This type is declared in `WinDef.h` as follows: + +typedef unsigned char UCHAR +""" +UCHAR + + +""" + const USHORT = Cushort + +An unsigned SHORT. + +This type is declared in `WinDef.h` as follows: + +`typedef unsigned short USHORT;` +""" +USHORT + +""" + const VOID = Cvoid + + +Any type. + +This type is declared in `WinNT.h` as follows: + +#define VOID void +""" +VOID + + +""" + const WCHAR = Cwchar_t + +A 16-bit Unicode character. + +This type is declared in `WinNT.h` as follows: + +`typedef wchar_t WCHAR;` +""" +WCHAR + +""" + const WORD = Cushort + +A 16-bit unsigned integer. + +This type is declared in `WinDef.h` as follows: + +`typedef unsigned short WORD;` +""" +WORD end