U/sgriffin/docs

README.md

@@ -2,4 +2,4 @@
 The MAPI Stub Library is a drop in replacement for mapi32.lib which supports building both 32 and 64 bit MAPI applications. This library eliminates the need to explicitly link to MAPI.
 
 **See the [documentation](https://learn.microsoft.com/en-us/office/client-developer/outlook/mapi/how-to-link-to-mapi-functions) for information on building the MAPI Stub Library and integrating it into your project.**\
-**See the [FAQ](https://mapistublibrary.codeplex.com/wikipage?title=FAQ) for questions about this library, such as when and why to use it.**
+**See the [FAQ](docs/FAQ.md) for questions about this library, such as when and why to use it.**

binding.gyp

@@ -1,12 +1,30 @@
 {
   "targets": [
     {
-      "target_name": "binding",
-      'include_dirs': ['include'],
+      "target_name": "MAPIStubLibrary",
+      "type": "static_library",
+      "include_dirs": ["include"],
       "sources": [
-          "library/mapiStubLibrary.cpp",
-          "library/stubutils.cpp"
-          ]
+        "library/mapiStubLibrary.cpp",
+        "library/stubutils.cpp"
+      ],
+      "msvs_version": "2022",
+      "msvs_settings": {
+        "VCCLCompilerTool": {
+          "RuntimeLibrary": 0, # /MT - static runtime
+          "ExceptionHandling": 0, # disable exceptions
+          "Optimization": 2, # /O2 instead of aggressive /Ox
+          "WarningLevel": 4
+        },
+        "VCLibrarianTool": {
+          "AdditionalOptions": ["/LTCG"] # Link Time Code Generation
+        }
+      },
+      "defines": [
+        "WIN32_LEAN_AND_MEAN",
+        "NOMINMAX"
+      ],
+      "product_dir": "lib/<(target_arch)"
     }
   ]
 }

docs/Building.md

@@ -0,0 +1,89 @@
+# Building the MAPI Stub Library
+
+To build the MAPI Stub Library as MAPIStubLibrary.lib, do the following:
+
+## Getting the Source
+
+You have two options to get the source code:
+
+1. **Clone the repository (recommended)**:
+
+   ```bash
+   git clone https://github.com/microsoft/MAPIStubLibrary.git
+   cd MAPIStubLibrary
+   ```
+
+2. **Download as ZIP**:
+   Download the [latest source](https://github.com/microsoft/MAPIStubLibrary/archive/refs/heads/main.zip) and extract it to a local directory.
+
+## Building with Visual Studio
+
+The project includes all necessary MAPI headers in the `include` directory, so no additional downloads are required.
+
+1. **Open the solution**: Open `mapistub.sln` in Visual Studio (2019 or later recommended).
+
+2. **Select configuration**: From the Solution Configuration dropdown, select:
+   - `Release` for production builds
+   - `Debug` for debugging purposes
+
+3. **Select platform**: From the Solution Platform dropdown, select:
+   - `x64` for 64-bit applications (recommended)
+   - `Win32` for 32-bit applications
+   - `ARM64` for ARM64 applications
+
+4. **Build**: Press `Ctrl+Shift+B` or go to Build → Build Solution.
+
+You now have a file, `MAPIStubLibrary.lib`, which you can link in to your project.
+
+## Building with Node.js/node-gyp
+
+Alternatively, you can build using Node.js and node-gyp (this creates a static library):
+
+1. **Install Node.js**: Make sure you have [Node.js](https://nodejs.org/) installed.
+
+2. **Install dependencies**:
+
+   ```bash
+   npm install
+   ```
+
+3. **Build**:
+
+   **Default build (matches your Node.js architecture):**
+
+   ```bash
+   npm run build
+   ```
+
+   **Architecture-specific builds:**
+
+   ```bash
+   npm run build:x64    # 64-bit library
+   npm run build:x86    # 32-bit library  
+   npm run build:arm64  # ARM64 library
+   ```
+
+   **Clean build artifacts:**
+
+   ```bash
+   npm run clean
+   ```
+
+The output will be `MAPIStubLibrary.lib` in the `build/Release` directory.
+
+## Build Output
+
+### Visual Studio Build
+
+After building with Visual Studio, you'll find:
+
+- `MAPIStubLibrary.lib` - The static library for linking
+- Debug symbols (if building in Debug configuration)
+
+### Node.js Build
+
+After building with node-gyp, you'll find:
+
+- `MAPIStubLibrary.lib` - The static library for linking in `build/Release/`
+
+Both build methods produce the same `MAPIStubLibrary.lib` static library that you can link into your C++ projects.

docs/DirectlyIncluding.md

@@ -0,0 +1,12 @@
+# Directly Including the MAPI Stub Library
+
+One way to incorporate the MAPI Stub Library is to copy the source files, [`MapiStubLibrary.cpp`](../library/mapiStubLibrary.cpp) and [`StubUtils.cpp`](../library/stubutils.cpp) directly into your project and remove any linkage to mapi32.lib as well as any code which explicitly links to MAPI. [MFCMAPI](https://github.com/microsoft/mfcmapi), which formerly implemented [Explicit Linking](http://msdn.microsoft.com/en-us/library/cc963763.aspx) to link to MAPI, uses this technique. If you're not already including msi.lib, you will need to either include it or manually load the MSI functions.
+
+If you need access to the stub utility functions (such as [`SetMAPIHandle`](../library/stubutils.h#L46) or [`UnloadPrivateMAPI`](../library/stubutils.h#L49)), you can optionally include the [`stubutils.h`](../library/stubutils.h) header file. This header provides declarations for functions that allow you to control MAPI loading behavior, force specific MAPI implementations, and manually manage MAPI module handles.
+
+Since the MAPI Stub Library implements all of the logic for loading MAPI for you, in MFCMAPI we were able to eliminate a large amount of code from ImportProcs.cpp which had previously handled locating MAPI and finding entry points to MAPI functions. A couple features in MFCMAPI changed during this integration, such as:
+
+- **Forcing MAPI to load from a user input path**: MFCMAPI can still do this, by loading the DLL as directed by the user, then using the [`SetMAPIHandle`](../library/stubutils.h#L46) function to inform the stub which module to use.
+- **Manually unloading MAPI**: The stub library implements a routine, [`UnloadPrivateMAPI`](../library/stubutils.h#L49), which MFCMAPI now uses to unload MAPI.
+
+Aside from including the source files as part of your build and adding msi.lib, there are no changes required to your code which makes MAPI calls."" 

docs/FAQ.md

@@ -0,0 +1,89 @@
+# FAQ - Frequently Asked Questions
+
+## When to use the MAPI Stub
+
+- [Why would I use this library?](#why-would-i-use-this-library)
+- [Can't I just use the 64 bit mapi32.lib that ships in the Microsoft SDK?](#cant-i-just-use-the-64-bit-mapi32lib-that-ships-in-the-microsoft-sdk)
+- [I explicitly link to MAPI. Do I need this library?](#i-explicitly-link-to-mapi-do-i-need-this-library)
+- [Doesn't this library just load the MAPI stub from the system directory?](#doesnt-this-library-just-load-the-mapi-stub-from-the-system-directory)
+- [My application is only 32 bit and uses mapi32.lib. Do I have to switch to this library?](#my-application-is-only-32-bit-and-uses-mapi32lib-do-i-have-to-switch-to-this-library)
+- [Do you have a list of functions linked from this library that aren't available in mapi32.lib?](#do-you-have-a-list-of-functions-linked-from-this-library-that-arent-available-in-mapi32lib)
+
+## Linking and building
+
+- [Can I just include the source of this library in my project?](#can-i-just-include-the-source-of-this-library-in-my-project)
+- [Where are the instructions for building this library?](#where-are-the-instructions-for-building-this-library)
+- [What about instructions for linking to it?](#what-about-instructions-for-linking-to-it)
+- [Why do I have to build this? Why can't I just download a pre-built .lib?](#why-do-i-have-to-build-this-why-cant-i-just-download-a-pre-built-lib)
+- [I use a compiler other than Visual Studio, or a different version of Visual Studio than one of the provided projects. What can I do?](#i-use-a-compiler-other-than-visual-studio-or-a-different-version-of-visual-studio-than-one-of-the-provided-projects-what-can-i-do)
+
+## Bugs
+
+- [I don't like the way the library does X. Can I change it?](#i-dont-like-the-way-the-library-does-x-can-i-change-it)
+- [The MAPI Stub Library doesn't export the function X. Can I add it?](#the-mapi-stub-library-doesnt-export-the-function-x-can-i-add-it)
+- [The MAPI Stub Library exports the function X incorrectly. Can I fix it?](#the-mapi-stub-library-exports-the-function-x-incorrectly-can-i-fix-it)
+
+**Didn't find what you're looking for here? Start a thread on the [discussion board](https://github.com/microsoft/MAPIStubLibrary/discussions).**
+
+## Why would I use this library?
+
+For years, MAPI was implemented as a 32 bit API. We provided a library, mapi32.lib, which programs could link to in order to get access to MAPI. Then along came Outlook 2010 and 64 bit MAPI. Since mapi32.lib was a 32 bit library, 64 bit programs needed something else in order to use MAPI. This project fills that gap.
+
+## Can't I just use the 64 bit mapi32.lib that ships in the Microsoft SDK?
+
+No - this is a bad implementation which doesn't locate MAPI properly and doesn't link to some MAPI functions correctly. It should be avoided.
+
+## I explicitly link to MAPI. Do I need this library?
+
+No, but you could look at eliminating your explicit linking code by linking to this library.
+
+## Doesn't this library just load the MAPI stub from the system directory?
+
+No, though that is a fallback mechanism. This library implements the technique discussed in [How to: Choose a Specific Version of MAPI to Load](http://msdn.microsoft.com/en-us/library/dd181963) to find Outlook's implementation of MAPI first. Only if this fails does it try the stub from the system directory.
+
+## My application is only 32 bit and uses mapi32.lib. Do I have to switch to this library?
+
+No, but doing so will give you better support for loading Outlook's MAPI in a wider variety of locales. It will also eliminate the need to write LoadLibrary/GetProcAddress code to handle newer exports which are included in this library but are not included in mapi32.lib.
+
+## Do you have a list of functions linked from this library that aren't available in mapi32.lib?
+
+Here's a partial list:
+
+- [GetDefCachedMode](http://msdn.microsoft.com/en-us/library/ff960261)
+- [HrGetGALFromEmsmdbUID](http://msdn.microsoft.com/en-us/library/ff522804)
+- [HrOpenOfflineObj](http://msdn.microsoft.com/en-us/library/ff960538)
+- [MAPICrashRecovery](http://msdn.microsoft.com/en-us/library/ff960295)
+- [OpenStreamOnFileW](http://msdn.microsoft.com/en-us/library/gg318092)
+- [WrapCompressedRTFStreamEx](http://msdn.microsoft.com/en-us/library/ff960302)
+
+## Can I just include the source of this library in my project?
+
+Yes! This is exactly how MFCMAPI does it. Read more about [Directly Including the MAPI Stub Library](DirectlyIncluding.md).
+
+## Where are the instructions for building this library?
+
+See: [Building the MAPI Stub Library](Building.md).
+
+## What about instructions for linking to it?
+
+See: [Linking To MAPIStubLibrary.lib](Linking.md).
+
+## Why do I have to build this? Why can't I just download a pre-built .lib?
+
+By providing full source and build projects for this library, we're giving complete control to the developer who uses it. This way, you're not dependent on us to provide new builds to correct any issues which may be uncovered in the library. Also, this gives the developer the flexibility to add and remove features from the library to fit their specific needs. This release mechanism does build in an assumption that the developer using this library is comfortable building a C++ project, but that's a safe assumption if they're already using MAPI.
+
+## I use a compiler other than Visual Studio, or a different version of Visual Studio than one of the provided projects. What can I do?
+
+You should still be able to use the provided source. You'll just have to build your own project or directly include the source in your existing project. Feel free to share your experiences in the [Discussions](https://github.com/microsoft/MAPIStubLibrary/discussions).
+
+## I don't like the way the library does X. Can I change it?
+
+Of course. Do whatever you like to the code. If you find bugs you wish to report, please visit the [Issues](https://github.com/microsoft/MAPIStubLibrary/issues) page.
+
+## The MAPI Stub Library doesn't export the function X. Can I add it?
+
+Yes. There are plenty of examples in [`MapiStubLibrary.cpp`](../library/mapiStubLibrary.cpp) of how to export a function. If the function is one we've documented, please file a "Missing Export" bug under Issues so we can consider adding it for everyone.
+
+## The MAPI Stub Library exports the function X incorrectly. Can I fix it?
+
+Yes. You can correct the export in [`MapiStubLibrary.cpp`](../library/mapiStubLibrary.cpp). Please also file an "Incorrect Export" bug under Issues so we can consider fixing it for everyone.

docs/Linking.md

@@ -0,0 +1,7 @@
+# Linking To MAPIStubLibrary.lib
+
+You can use the MAPI Stub Library as a drop in replacement for mapi32.lib. Once you've built MAPIStubLibrary.lib, you can remove mapi32.lib from your linker settings and replace it with MAPIStubLibrary.lib. No further modifications to your code should be necessary.
+
+ExampleMapiConsoleApp demonstrates this technique. Note that ExampleMapiConsoleApp.cpp includes the regular MAPI headers and has no code dedicated to loading MAPI dlls. When the first MAPI call is made, in this case, MAPIInitialize, the stub library takes care of looking up the location of Outlook's implementation of MAPI so it can load it and dispatch the call. Subsequent MAPI calls continue to use the same dll, lining up entry points with GetProcAddress.
+
+For more information, see [Building the MAPI Stub Library](Building.md).

library/stubutils.h

@@ -4,7 +4,7 @@
 #include <string>
 
 // stubutils.h - Optional header to enable clients to reuse stubutils code
-// Not reuqired to build the mapistub library
+// Not required to build the mapistub library
 
 namespace mapistub
 {

package.json

@@ -1,4 +1,15 @@
 {
+  "name": "mapistublibrary",
+  "version": "1.0.0",
+  "description": "MAPI Stub Library for 32 and 64 bit applications",
+  "scripts": {
+    "build": "node-gyp rebuild",
+    "build:x64": "node-gyp rebuild --arch=x64",
+    "build:x86": "node-gyp rebuild --arch=ia32",
+    "build:arm64": "node-gyp rebuild --arch=arm64",
+    "clean": "node-gyp clean",
+    "clean:all": "node-gyp clean && rmdir /s /q build 2>nul || true"
+  },
   "devDependencies": {
     "clang-format": "^1.8.0"
   }