Mapi

MAPI Microsoft MAPI 1.0, also known as Extended MAPI, defines a complete architecture for messaging applications. MAPI is a set of functions that applications can use to create, manipulate, transfer, and store messages.The MAPI architecture can be used for such applications as E-mail, scheduling, personal information managers, bulletin boards, and online services (all of which can run on a broad range of platforms). MAPI also offers a common interface that developers can use to build E-mail-enabled applications independently of the underlying messaging system. MAPI takes its design from the Windows printing model. Just as Windows enables applications to print to several different sources (via a print spooler and independent printer drivers), MAPI enables messaging applications to run with several different messaging services. The MAPI architecture defines both messaging clients and messaging services. To use a service, a client must first set up a session, which is a specific connection between the client and MAPI based on data included in a profile (which lists configuration information).Once the session is established, the client can access MAPI services, which fall into three basic categories: Address Books, which might be thought of as telephone directories. These are a collection of one or more lists of message recipients. Each list is known as a container. Custom address books are supported. Message Transports, which transfer messages among clients. MAPI message transports support interaction among a variety of hardware platforms and messaging systems. Message Stores, which organize and store messages and allow them to be accessed. Messages are kept in folders, which are organized hierarchically. In addition, the user can alter messages and then put them back in their folders. A user who received a Microsoft Excel spreadsheet as an OLE object in a message, forexample, could run Excel from within the message, modify the file,and then save the modified file as part of the message.

MAPI Programming Interfaces As Figure 1 shows, Microsoft offers a variety of programming interfaces for MAPI 1.0, allowing developers in many different development environments to use MAPI. The OLE Messaging Library does not provide access to all of the Features of Extended MAPI. For example, it is intended primarily for clients and is not appropriate for service providers.The following table details the programming interfaces offered for MAPI 1.0. ProgrammingInterface Description MAPI customcontrols User interfacefor Visual Basic users. Simple MAPI

Simplifiedinterface containing 12 common API calls. OLE MessagingLibrary 1.0 Programmableobjects for use by Visual Basic and VBA developers. CMC API calls forC and C++ users (described later in thisDevNote) Extended MAPI OLE interfacesfor C and C++ programmers.

Application programming interface An application programming interface (API) is a source code interface that a computer system or program library provides in order to support requests for services to be made of it by a computer program. An API differs from an application binary interface in that it is specified in terms of a programming language that can be compiled when an application is built, rather than an explicit low level description of how data is laid out in memory. The software that provides the functionality described by an API is said to be an implementation of the API. The API itself is abstract, in that it specifies an interface and does not get involved with implementation details. A well known API is the Single UNIX Specification. An API is often a part of a software development kit (SDK). The term API is used in two related senses: • •

A coherent interface consisting of several classes or several sets of related functions or procedures. A single entry point such as a method, function or procedure.

Design models There are various design models for APIs. Interfaces intended for the fastest execution often consist of sets of functions, procedures, variables and data structures. However, other models exist as well - such as the interpreter used to evaluate expressions in ECMAScript/JavaScript or in the abstraction layer - which relieve the programmer from needing to know how the functions of the API relate to the lower levels of abstraction. This makes it possible to redesign or improve the functions within the API without breaking code that relies on it. Some APIs, such as the ones standard to an operating system, are implemented as separate code libraries that are distributed with the operating system. Others require

software publishers to integrate the API functionality directly into the application. This forms another distinction in the examples above. Microsoft Windows APIs come with the operating system for anyone to use. Software for embedded systems such as video game consoles generally falls into the application-integrated category. While an official PlayStation API document may be interesting to read, it is of little use without its corresponding implementation, in the form of a separate library or software development kit. An API that does not require royalties for access and usage is called "open".[1] Although usually authoritative "reference implementations" exist for an API (such as Microsoft Windows for the Win32 API), there is nothing that prevents the creation of additional implementations. For example, most of the Win32 API can be provided under a UNIX system using software called Wine. In countries subject to software patents it is sometimes lawful to analyze API implementations in order to produce a compatible one. This technique is called reverse engineering for the purposes of interoperability. However, the legal situation is often ambiguous, so that care and legal counsel should be taken before the reverse engineering is carried out. For example, while APIs usually do not have an obvious legal status, they might include patents that may not be used until, and if, the patent holder gives permission. Many countries however do not grant software patents and within these countries only the protection of copyright applies to an API.

Release policies Two general lines of API publishing policies: 1. Some companies protect information on their APIs from the general public. For example, Sony used to make its official PlayStation 2 API available only to licensed PlayStation developers. This enabled Sony to control who wrote PlayStation 2 games. Such control can have quality control benefits and potential license revenue. 2. Some companies make their APIs freely available. For example, Microsoft makes most of its API information public, so that software will be written for the Windows platform. It is to be expected that companies base their choice of publishing policy on maximizing benefit to themselves.

Windows API The Windows API, informally WinAPI, is the name given by Microsoft to the core set of application programming interfaces available in the Microsoft Windows operating systems. It is designed for use by C/C++ programs and is the most direct way to interact with a Windows system for software applications. Lower level access to a Windows

system, mostly required for device drivers, is provided by the Windows Driver Foundation in current versions of Windows. A software development kit (SDK) is available for Windows, which provides documentation and tools to enable developers to create software using the Windows API and associated Windows technologies.

Overview of the Windows API Components The functionality provided by the Windows API can be grouped into seven categories:[1] Base Services[2] Provide access to the fundamental resources available to a Windows system. Included are things like file systems, devices, processes and threads, access to the Windows registry, and error handling. These functions reside in kernel.exe, krnl286.exe or krnl386.exe files on 16-bit Windows, and kernel32.dll and advapi32.dll on 32-bit Windows. Graphics Device Interface[3] Provide the functionality for outputting graphical content to monitors, printers and other output devices. It resides in gdi.exe on 16-bit Windows, and gdi32.dll on 32-bit Windows. User Interface[4] Provides the functionality to create and manage screen windows and most basic controls, such as buttons and scrollbars, receive mouse and keyboard input, and other functionality associated with the GUI part of Windows. This functional unit resides in user.exe on 16-bit Windows, and user32.dll on 32-bit Windows. Since Windows XP versions, the basic controls reside in comctl32.dll, together with the common controls (Common Control Library). Common Dialog Box Library[5] Provides applications the standard dialog boxes for opening and saving files, choosing color and font, etc. The library resides in a file called commdlg.dll on 16-bit Windows, and comdlg32.dll on 32-bit Windows. It is grouped under the User Interface category of the API. Common Control Library[6] Gives applications access to some advanced controls provided by the operating system. These include things like status bars, progress bars, toolbars and tabs. The library resides in a DLL file called commctrl.dll on 16-bit Windows, and comctl32.dll on 32-bit Windows. It is grouped under the User Interface category of the API. Windows Shell[7][8] Component of the Windows API allows applications to access the functionality provided by the operating system shell, as well as change and enhance it. The component resides in shell.dll on 16-bit Windows, and shell32.dll and later in Windows 95 shlwapi.dll on 32-bit Windows. It is grouped under the User Interface category of the API. Network Services[9]

Give access to the various networking capabilities of the operating system. Its sub-components include NetBIOS, Winsock, NetDDE, RPC and many others.

Web related APIs The Internet Explorer web browser also exposes many APIs that are often used by applications, and as such could be considered a part of the Windows API. Internet Explorer has been an integrated component of the operating system since Windows 98, and provides web related services to applications [10]. The integration will stop with Windows Vista. Specifically, it provides: • •

• • • •

An embeddable web browser control, contained in shdocvw.dll and mshtml.dll. The URL monikers service, held in urlmon.dll, which provides COM objects to applications for resolving URLs. Applications can also provide their own URL handlers for others to use. A library for assisting with multi-language and international text support (mlang.dll). DirectX Transforms, a set of image filter components. XML support (the MSXML components). Access to the Windows Address Book.

Multimedia related APIs Microsoft has provided the (DirectX) set of APIs as part of every Windows installation since Windows 95 OSR2. DirectX provides a loosely related set of multimedia and gaming services, including: • •

• • •

•

•

Direct3D as an alternative to OpenGL for access to 3D acceleration hardware. DirectDraw for hardware accelerated access to the 2D framebuffer. As of DirectX 9, this component has been deprecated in favor of Direct3D, which provides more general high-performance graphics functionality (2D rendering, after all, is really just a subset of 3D rendering). DirectSound for low level hardware accelerated sound card access. DirectInput for communication with input devices such as joysticks and gamepads. DirectPlay as a multiplayer gaming infrastructure. This component has been deprecated as of DirectX 9 and Microsoft no longer recommends its use for game development. DirectShow which builds and runs generic multimedia pipelines. It is comparable to the GStreamer framework and is often used to render in-game videos and build media players (Windows Media Player is based upon it). DirectShow is no longer recommended for game development. DirectMusic

APIs for interaction between programs

The Windows API mostly concerns itself with the interaction between the Operating System and an application. For communication between the different Windows applications among themselves, Microsoft has developed a series of technologies alongside the main Windows API. This started out with Dynamic Data Exchange (DDE), which was superseded by Object Linking and Embedding (OLE) and later by the Component Object Model (COM).

Wrapper Libraries Various wrappers were developed by Microsoft that took over some of the more low level functions of the Windows API, and allowed applications to interact with the API in a more abstract manner. Microsoft Foundation Class Library (MFC) wrapped Windows API functionality in C++ classes, and thus allows a more object oriented way of interacting with the API. The Active Template Library (ATL) is a template oriented wrapper for COM. The Windows Template Library (WTL) was developed as an extension to ATL, and intended as a lightweight alternative to MFC. Also notable are some of Borland's offerings. Object Windows Library (OWL) was released as a competing product to MFC, and offered a similar object-oriented wrapper. Borland later deprecated it in favour of the Visual Component Library (VCL). All application frameworks for Windows are (at least partially) wrapping the Windows API. Thus, the .NET Framework and Java, as well as any other programming languages under Windows, are (or contain) Wrapper Libraries.

History The Windows API has always exposed a large part of the underlying structure of the various Windows systems for which it has been built to the programmer. This has had the advantage of giving Windows programmers a great deal of flexibility and power over their applications. However, it also has given Windows applications a great deal of responsibility in handling various low-level, sometimes tedious, operations that are associated with a graphical user interface. Charles Petzold, writer of well-read Windows API books, has said: "The original helloworld program in the Windows 1.0 SDK was a bit of a scandal. HELLO.C was about 150 lines long, and the HELLO.RC resource script had another 20 or so more lines. (...) Veteran C programmers often curled up in horror or laughter when encountering the Windows hello-world program."[11] A Hello world program is a frequently used programming example, usually designed to show the easiest possible application on a system that can actually do something (i.e. print a line that says "Hello World"). Over the years, various changes and additions were made to the Windows Operating System, and the Windows API changed and grew to reflect this. The Windows API for Windows 1.0 supported fewer than 450 function calls, where in modern versions of the Windows API there are thousands. However, in general, the interface remained fairly

consistent, and an old Windows 1.0 application will still look familiar to a programmer who is used to the modern Windows API.[12] A large emphasis has been put by Microsoft on maintaining software backwards compatibility. To achieve this, Microsoft sometimes even went as far as supporting software that was using the API in a undocumented or even (programmatically) illegal way. Raymond Chen, a Microsoft developer who works on the Windows API, has said: "I could probably write for months solely about bad things apps do and what we had to do to get them to work again (often in spite of themselves). Which is why I get particularly furious when people accuse Microsoft of maliciously breaking applications during OS upgrades. If any application failed to run on Windows 95, I took it as a personal failure."[13] One of the largest changes the Windows API underwent was the transition from Win16 (shipped in Windows 3.1 and older) to Win32 (Windows NT and Windows 95 and up). While Win32 was originally introduced with Windows NT 3.1 and Win32s allowed usage of a Win32 subset before Windows 95, it was not until Windows 95 that many applications began being ported to Win32. To ease the transition, in Windows 95, both for external developers and for Microsoft itself, a complex scheme of API thunks was used that could allow 32 bit code to call into 16 bit code and (in limited cases) vice-versa. Socalled flat thunks allowed 32 bit code to call into 16 bit libraries, and the scheme was used extensively inside Windows 95 to avoid porting the whole OS to Win32 itself in one chunk. In Windows NT, the OS was pure 32-bit (except the parts for compatibility with 16-bit applications) and the only thunk available was generic thunks which only thunks from Win16 to Win32 and worked in Windows 95 too. The Platform SDK shipped with a compiler that could produce the code necessary for these thunks.

Versions Almost every new version of Microsoft Windows has introduced its own additions and changes to the Windows API. [14] The name of the API however was kept consistent between different Windows version, and name changes were kept limited to major architectural and platform changes for Windows. Microsoft eventually changed the name of the then current Win32 API family into Windows API, and made it into a catch-all term for both past and future versions of the API. [15] •

•

Win16 was the API for the first, 16-bit versions of Microsoft Windows. These were initially referred to as simply the Windows API, but were later renamed to Win16 in an effort to distinguish it from the newer, 32-bit version of the Windows API. The functions of Win16 API mainly reside in the core files of the OS: kernel.exe (or krnl286.exe or krnl386.exe), user.exe and gdi.exe. Despite the file extension of exe, these actually are dynamically linked libraries. Win32 is the 32-bit API for modern versions of Windows. The API consists of functions implemented, as with Win16, in system DLLs. The core DLLs of Win32 are kernel32.dll, user32.dll, and gdi32.dll. Win32 was introduced with Windows NT. The version of Win32 that was shipped with Windows 95 was initially

•

•

referred to as Win32c, with the "c" standing for "compatibility", but this term was later abandoned by Microsoft in favour of Win32. In Windows NT 4.0 and its successors (including all modern Windows versions), Win32 calls are executed by two modules, csrss.exe (Client/Server Runtime Server Subsystem) in user mode and win32k.sys in kernel mode. [16] Win32s is an extension for the Windows 3.1x family of Microsoft Windows that implemented a subset of the Win32 API for these systems. The "s" stands for "subset". Win32 for 64-bit Windows, previously known as Win64, is the version of the API targeted for 64-bit versions of Windows — namely, Windows XP Professional x64 Edition and Windows Server 2003 x64 Edition (for AMD64 processors) and Windows XP 64-bit Edition and Windows Server 2003 for Itanium-series. The 64-bit versions are just two more supported platforms within Windows NT architecture so both 32-bit and 64-bit versions of an application can still be compiled from single code base. All memory pointers are 64-bit by default though, so the source code has to be checked for compatibility with 64-bit pointer arithmetic and rewritten as necessary. There are no new functions specific to 64bit versions of Windows.

[edit] Other implementations Although Microsoft's implementation of the Windows API is copyrighted, it is generally accepted due to legal precedents[citation needed] in the United States that other vendors can emulate Windows by providing an identical API, without breaching copyright. The Wine project is an attempt to provide a Win32 API Compatibility layer for Unix-like platforms. ReactOS goes a step further and provides an emulation of the entire Windows operating system, working closely with the Wine project to promote code re-use and compatibility. HX DOS-Extender (external link) is another project to emulate the Windows API, to allow running simple Windows programs from a DOS command line.

[edit] Compiler support To develop software that utilizes the Windows API, a compiler must be able to handle and import the Microsoft-specific DLLs and COM-objects. The compiler must accept a C or C++ language dialect and handle IDL (interface definition language) files and header files that expose the interior API function names. Collectively, these prerequisites (compilers, tools, libraries, and headers) are known as the Microsoft Platform SDK. For a long time the proprietary Microsoft Visual Studio family of compilers and tools and Borland's compilers were the only tools that could provide this (although at least in the case of Windows, the SDK itself is downloadable for free separately from the entire IDE suite, from Microsoft Platform SDK Update). Nowadays the MinGW and Cygwin projects also provide such an environment based on the GNU Compiler Collection, using a stand-alone header file collection to make linking against Microsoft DLLs possible. LCC-Win32 is a "free for non-commercial use" C compiler maintained by Jacob Navia (a

comp.lang.c regular). Pelles C is a free C compiler maintained by Pelle Orinius. Free Pascal is a GPL Object Pascal compiler capable of writing software based on the Windows API. MASM32 is a mature project to support the Windows API utilizing the 32 bit Microsoft assembler with custom made or converted headers and libraries from the Platform SDK. Windows specific compiler support is also required for the Structured Exception Handling feature (SEH). This system serves a dual purpose: it provides a substrate upon which language-specific exception handling can be implemented, and it is how the kernel notifies applications of exceptional conditions such as dereferencing an invalid pointer or stack overflow. The Microsoft/Borland C++ compilers had the ability to use this system as soon as it was introduced in Windows 95 and NT, however the actual implementation was undocumented and had to be reverse engineered for the Wine project and free compilers. SEH is based on pushing exception handler frames onto the stack, then adding them to a linked list stored in thread local storage (the first field of the thread environment block). When an exception is thrown, the kernel and base libraries unwind the stack running handlers and filters as they are encountered. Eventually, every exception unhandled by the application itself will be dealt with by the default backstop handler which pops up the Windows common crash dialog. Example of API implementation in Visual Basic: (this shortened example causes the Command button to be able to be moved around on the form by the user) Private Const WM_NCLBUTTONDOWN As Long = &HA1& Private Const HTCAPTION As Long = 2& Private Declare Function ReleaseCapture Lib "user32" () As Long Private Declare Function SendMessage Lib "user32" Alias "SendMessageA" (ByVal hWnd&, ByVal wMsg&, wParam As Any, lParam As Any) As Long If Command1.MousePointer = 14 Then Call ReleaseCapture Call SendMessage(Command1.hWnd, WM_NCLBUTTONDOWN, ByVal HTCAPTION, ByVal 0&) End If