Small helper library to make Microsoft RPC API more accessible with mingw compiler
C Vala Python Shell

README

                                 msrpc-mingw


This is a package aiming to simplify use of the Microsoft RPC API from
the mingw (gcc) compiler.

Some documentation can be found in the src/msrpc-mingw.h and
src/msrpc-glib2.h files.


* Building:

WARNING: do not try to build inside a path which contains spaces! This also
applies to any project which uses midl-wrapper as part of its build process!

./waf configure  (if MIDL.EXE is not found, set the MIDL enviroment variable
                  to point to its location)
./waf
./waf install


* Components:

bin/midl-wrapper:
  helper script which runs MIDL.EXE (the MS interface compiler) and cleans
  up its output so that it will compile with gcc.

msrpc.py:
  waf plugin to provide an 'msrpc' tool

m4macros/msrpc-mingw-1.0.m4:
  autoconf macro to detect MIDL.EXE and the msrpc libraries. It's
  recommended that you copy this to your source tree if you use it,
  because otherwise your app will depend on this package on every
  platform it supports.

msrpc-mingw library:
  minimal C library to save you from having to call lengthy Windows
  API functions.

msrpc-glib2 library:
  GLib integration

vapi/msrpc-1.0.vapi
  Vala integration

tests/:
  Functional tests, with test runner to coordinate the client & server
  processes. See section 'testing'.


* Requirements:

You currently need to patch the mingw w32api package (which provides the
C headers and libraries for the Windows API) to add some missing RPC functions.

The patch is on the mingw bug tracker:
  https://sourceforge.net/tracker/?func=detail&aid=3302807&group_id=2435&atid=302435

The source is here:
  http://sourceforge.net/projects/mingw/files/MinGW/BaseSystem/RuntimeLibrary/Win32-API/w32api-3.17/w32api-3.17-2-mingw32-src.tar.lzma/download

Alternatively, here is a ready-patched version which you can just unzip inside
your mingw base directory:
  http://afuera.me.uk/junk/w32api-3.17-2-mingw-patch3302807-dev.tar.lzma

You also must have a copy of MIDL.EXE from the Windows SDK. This is available here:
  https://www.microsoft.com/downloads/en/details.aspx?FamilyID=c17ba869-9671-4330-a63e-1fd44e0e2505&displaylang=en

You need only install the 'Win32 developer tools' component.


* Documentation:

This can be found in the header files in src/. Look at the tests for more
examples of how to use this code.

Watch out for the following little traps that the API has in store:

  - Any output parameters which are pointers must be initialised to NULL
    before calling an RPC function, otherwise you will get a segfault.

  - When returning data, make sure it has been freshly allocated with
    in the server and that it gets freed in the client.

  - Make sure your MIDL_user_allocate() and MIDL_user_free() functions
    match up with the allocation API that you actually use for data that
    is sent or received over RPC. If you use msrpc-glib2, these
    functions are already defined to use g_malloc() and g_free().


* Testing:

To run the automated tests, make sure the build is up to date by running
'./waf'; install the library by running './waf install' and then run
'./waf check'.

FIXME: currently the tester will hang if you don't have the libraries
installed.

To test multi-user security, the rpctester program needs a dummy account
set up. This must be done manually: first, go to Control Panel > User
Accounts and create a new user account named 'test' (it does not need to
be an administrator). Create a password for it to be 'test'. Secondly,
run the policy editor SECPOL.MSC and go to Local Policies > User Rights
Assignment. In here, click on 'Replace a process level token' and add
'test' to the list. This allows rpctester.exe to use the
CreateProcessAsUser() API call to run one instance of the server as your
account and one as the test user, and check that the one cannot be
accessed from by other.


* Why not use DBus?

DBus is a system component. An ideal port of DBus to Windows would maintain
the interface while using MS RPC underneath; it's simply wrong to require
another system service to be running on Windows which doesn't belong there.
Since this doesn't exist, the next-best thing is to use MS RPC directly.


* Why not use DCOM?

DCOM is actually built on top of MS RPC.


* License

Copyright (c) 2011, JANET(UK)
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
 
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

3. Neither the name of JANET(UK) nor the names of its contributors
   may be used to endorse or promote products derived from this software
   without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.

Author: Sam Thursfield <samthursfield codethink co uk>