A C++11 header-only library for Microsoft Exchange Web Services.
You can find a couple of small executable examples in the examples/ folder.
As an appetizer, this is how it looks when you create and send an email message with ews-cpp:
#include <ews/ews.hpp>
#include <exception>
#include <iostream>
#include <ostream>
#include <string>
#include <vector>
int main() {
ews::set_up();
try {
auto service = ews::service("https://example.com/ews/Exchange.asmx",
"ACME",
"myuser",
"mysecret");
auto message = ews::message();
message.set_subject("Test mail from outer space");
std::vector<ews::mailbox> recipients{ ews::mailbox("[email protected]") };
message.set_to_recipients(recipients);
auto text = ews::body("ようこそ (Welcome!)\n\nThis is a test.\n");
message.set_body(text);
service.create_item(message, ews::message_disposition::send_and_save_copy);
} catch (std::exception& exc) {
std::cout << exc.what() << std::endl;
}
ews::tear_down();
return 0;
}We host automatically generated API documentation here: otris.github.io/ews-cpp.
EWS is an API that third-party programmers can use to communicate with Microsoft Exchange Server. The API exists since Exchange Server 2007 and is continuously up-dated by Microsoft and present in the latest iteration of the product, Exchange Server 2016.
This library provides a native and platform-independent way to use EWS in your C++ application.
- Most items are supported:
<CalendarItem>,<Message>,<Contact>,<Task>. Note that we still don't support all properties of all of these items. But we're working on it. - We support
<CreateItem>,<SendItem>,<FindItem>,<GetItem>,<UpdateItem>, and<DeleteItem>operations. <CreateFolder>,<GetFolder>,<DeleteFolder>,<FindFolder>operations on folders.- Basic support for attachments:
<CreateAttachment>,<GetAttachment>,<DeleteAttachment>for file attachments. Note: Item attachments are not supported yet. - Allow someone else to manage your mail and calendar:
- Impersonation. When you have a service process that needs to do regular tasks for a group of mailboxes or every mailbox in a database.
- Delegate access. For granting access to individual users. You can add permissions individually to each mailbox and directly modify folder permissions.
- Discovering Exchange servers in your network with Autodiscover is supported.
- EWS notification operations (
<Subscribe>,<GetEvents>,<Unsubscribe>) to inform you about specific item or folder changes are supported.
- HTTP basic auth
- NTLM
- OAuth2 (Client credentials flow)
Note: Kerberos is currently not supported but its on the TODO list.
- For using OAuth2 (client credentials flow), the client needs to be registered in the Azure tenant and granted the application permission "FullAccess".
- For an example see the file office365_oauth2.cpp.
- Microsoft Visual Studio since VS 2012
- Clang since 3.5
- with libc++ on Mac OS X
- with libstdc++ on Linux (Note that libc++ on Linux is not supported)
- GCC since 4.8 with libstdc++
- Microsoft Windows 10
- macOS starting with 10.12
- RHEL 7
- Ubuntu starting with 16.04 LTS
- Microsoft Exchange Server 2013 SP1
However, our goal is to support all Exchange Server versions since 2007.
The only thing you need for ews-cpp to run is libcurl.
If you want to hack on ews-cpp itself you additionally need
- Git
- CMake
- Doxygen (optional)
- Python 2 or 3 (optional)
You can obtain an up-to-date and easy-to-use binary distribution of libcurl from here: confusedbycode.com/curl
Additionally, you probably need to tell CMake where to find it. Just set
CMAKE_PREFIX_PATH to the path where you installed libcurl (e.g.
C:\Program Files\cURL) and re-configure.
You can also use the Windows batch script provided in
scripts\build-curl.bat to download and compile libcurl for your particular
version of Visual Studio.
ews-cpp's source code is available as a Git repository. To obtain it, type:
git clone --recursive https://github.com/otris/ews-cpp.gitThe library is header-only. So there is no need to build anything. Just copy the
include/ews/ directory wherever you may like.
To build the accompanied tests with debugging symbols and Address Sanitizer enabled do something like this:
cmake -DCMAKE_BUILD_TYPE=Debug -DENABLE_SANITIZERS=ON /path/to/source
makeType make edit_cache to see all configuration options. make help shows you
all available targets.
To build the tests and examples on Windows you can use cmake-gui. For more
see: https://cmake.org/runningcmake/
If you do not want to use any GUI to compile the examples and tests you could
do something like this with the Windows cmd.exe command prompt:
set PATH=%PATH%;C:\Program Files (x86)\CMake\bin
mkdir builddir
cd builddir
cmake -G "Visual Studio 14 2015 Win64" ^
-DCURL_LIBRARY="C:\Program Files\cURL\7.49.1\win64-debug\lib\libcurl_debug.lib" ^
-DCURL_INCLUDE_DIR="C:\Program Files\cURL\7.49.1\win64-debug\include" ^
C:\path\to\source
cmake --build .Make sure to choose the right generator for your environment.
Use the doc target to create the API documentation with Doxygen. Type:
make doc
open html/index.htmlIn order to run individual examples or the test suite export following environment variables like this:
export EWS_TEST_DOMAIN="DUCKBURG"
export EWS_TEST_USERNAME="mickey"
export EWS_TEST_PASSWORD="pluto"
export EWS_TEST_URI"https://hire-a-detective.com/ews/Exchange.asmx"Be sure to change the values to an actual account on some Exchange server that you can use for testing. Do not run the tests on your own production account.
Once you've build the project, you can execute the tests with:
./tests --assets=/path/to/source/tests/assetsIf you do not have any Exchange server available for testing you can run a subset of the tests that do not require a running server like this:
EWS_TEST_DOMAIN="" EWS_TEST_USERNAME="" EWS_TEST_PASSWORD="" EWS_TEST_URI="" ./tests \
--assets=$HOME/src/ews-cpp/tests/assets \
--gtest_filter=Offline\*.\*ews-cpp is written in a "modern C++" way:
- C++ Standard Library, augmented with rapidxml for XML parsing
- Smart pointers instead of raw pointers
- Pervasive RAII idiom
- Handle errors using C++ exceptions
- Coding conventions inspired by Boost
Just add:
#include <ews/ews.hpp>to your include directives and you are good to go.
Take a look at the examples/ directory to get an idea of how the API feels.
ews-cpp is a thin wrapper around Microsoft's EWS API. You will need to refer to
the EWS reference for
Exchange
for all available parameters to pass and all available attributes on items.
From 10.000ft it looks like this:
You have items and you have the service. You use the service whenever you want to talk to the Exchange server.
Please note one important caveat though. ews-cpp's API is designed to be "blocking". This means whenever you call one of the service's member functions to talk to an Exchange server that call blocks until it receives a request from the server. And that may, well, just take forever (actually until a timeout is reached). You need to keep this in mind in order to not block your main or UI thread.
Implications of this design choice
Pros:
- A blocking API is much easier to use and understand
Cons:
- You just might accidentally block your UI thread
- You cannot issue thousands of EWS requests asynchronously simply because you cannot spawn thousands of threads in your process. You may need additional effort here
- EWS Editor is an excellent Open Source tool to test EWS Managed API and do raw SOAP POSTs. Sources are available here: github.com/dseph/EwsEditor.
- This article on blogs.msdn.microsoft.com describing best practices in EWS Authentication and solving access issues.
ews-cpp is developed by otris software AG and was initially released to the public in July 2016. It is licensed under the Apache License, Version 2.0 (see LICENSE file).
For more information about otris software AG visit our website otris.de or our Open Source repositories at github.com/otris.