Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/aaronrobinsonmsft/dncp
https://github.com/aaronrobinsonmsft/dncp
Last synced: about 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/aaronrobinsonmsft/dncp
- Owner: AaronRobinsonMSFT
- Created: 2022-05-31T16:44:50.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-01-17T00:08:51.000Z (12 months ago)
- Last Synced: 2024-10-13T20:31:28.473Z (3 months ago)
- Language: C
- Size: 75.2 KB
- Stars: 1
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
Awesome Lists containing this project
README
# .NET COM Platform Abstraction Layer
A library to support porting C/C++ COM binaries from [.NET Framework][netfx_download] (Windows only) to a [.NET cross-platform][dotnet_download] environment.
## Requirements
The following are required to consume DNCP.
* [C11](https://en.cppreference.com/w/c/language/history) compatible compiler.
* [CMake](https://cmake.org/download/) – minimum is 3.6.2.
## Build
The root of the project contains a `dncp.proj` file that should be used to build. Directly using CMake is possible but since it is assume the .NET SDK is installed on the system it is recommended to use the `dotnet` command. The common `build`, `clean` and `test` commands are supported. For example, `dotnet build` will build the project.
## Test
Unit and scenario test the library using `dotnet test`.
## Usage
The recommended way to use DNCP is via [git submodules][git_submodules] and CMake.
The [`dncp.h`](./src/inc/dncp.h) header contains consistent definitions of common COM APIs. All data types are identically named to those in official Windows' headers. All functions are prefixed with `PAL_` followed by the official Win32 name (for example, `SysAllocString` is `PAL_SysAllocString`). Ideally, all functions provided by DNCP replace the corresponding Win32 APIs as DNCP will forward to the Windows implementation when running on Windows – see [`windows.c`](./src/windows.c).
The following defines are set when referencing the `dncp::winhdrs` target:
* `DNCP_TYPEDEFS` – Defines the most common Win32 data types needed for .NET scenarios. If this isn't set, the project should define them or include the official Windows' headers.
* `DNCP_WINHDRS` – Includes the minimal mocked out Windows' headers provided by DNCP. This is typically needed if building on non-Windows and/or referencing official .NET headers (for example, [`cor.h`](https://github.com/dotnet/runtime/blob/main/src/coreclr/inc/cor.h)).
### Walkthrough
These steps are the general process. Note that depending on how complex your project is, these may not be sufficient.
1. Add DNCP as a submodule to your repository.
- `git submodule add https://github.com/AaronRobinsonMSFT/DNCP.git`
1. Include in your build with CMake's [`FetchContent` module](https://cmake.org/cmake/help/latest/module/FetchContent.html).
```cmake
include(FetchContent)
FetchContent_Declare(
dncp
SOURCE_DIR DNCP
)
FetchContent_MakeAvailable(dncp)
```
1. Reference the `dncp.h` header and link the DNCP static library into the target project.
```c
#include
```
```cmake
target_link_libraries(mycomlib dncp::dncp)
```
1. For non-Windows build or if you are trying to avoid referencing any Windows header files, link to the `dncp::winhdrs` target as well.
```cmake
target_link_libraries(mycomlib dncp::winhdrs)
```
An example of consumption can be found in the [scenario test project](./tests/scenario/comserver/CMakeLists.txt).
## FAQs
1. The implementation of some string functions don't check for `NULL` inputs, this makes the APIs less robust. Why don't they check for `NULL`?
- DNCP is designed to be a drop in replacement for the APIs on Win32. The intent is to match semantics identically. This is reflected in the unit tests when they run on Windows.
[dotnet_download]: https://dotnet.microsoft.com/download
[netfx_download]: https://dotnet.microsoft.com/download/dotnet-framework
[git_submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules