Midas SDK Documentation v1.0

Miranda .net Association Plugin SDK, © 2006 Virtuoso

Contents

• Overview
• Architecture
• Namespaces
  • Key namespaces
  • Native interop namespaces
• Classes
  • Key classes
    • Plugin definition/construction classes
    • Miranda API wrapper classes
  • Native interop classes
  • Helper classes
• A Hello World plugin Walkthrough

Overview

Midas (Miranda .net Assocication Plugin) is a plugin allowing Microsoft.net platform developers to access Miranda APIs thus allowing them to write Miranda targeted managed plugins.

I created Midas because I'm an avid C# programmer and I wanted to extend Miranda in an easy, reliable and fast way - with Microsoft.net managed plugins.

You can write Miranda plugins in any Ecma CLI compliant language, for example C#, J#, Delphi, C++/CLI or Visual Basic.net. Please note that you may not be able to take advantage of all Midas features from languages that do not support some CLS non-compliant constructs. You may have problems using Microsoft Visual Basic.net because it, for example, does not support unsigned data types. Miranda and Midas use these types (System.UIntPtr) extensively.

In a nutshell, Midas represents a native-to-managed wrapper presenting core Miranda APIs in the OO fashion to .net. It wraps Miranda's procedural APIs to a neat and logical object oriented interface.

Using Midas, you can write Miranda plugins that you or anybody else find useful. With .net plugins, you can accomplish complicated and complex tasks in the much faster way.

Architecture

Midas consinsts of two crucial assemblies:

• Midas.dll
  • this assembly was written in IL (Intermediate Language) and contains 3 unmanaged exports exposing required unmanaged plugin API exports to Miranda
  • previously, there was an C++/CLI assembly but it's maintentace was not as easy as it ought to be (and me, primarily .net programmer, concluded a pure IL assembly as a more transparent way to accomplish the connection with Miranda than the opaque IJW magic C++/CLI compiler uses)
  • this assembly instantiates the Virtuoso.Midas.Loader class that provides Miranda with a PLUGININFO information and initiates the .net plugins fusion
• Virtuoso.Miranda.Plugins.dll
  • this assembly was written in safe C# and exposes unmanaged Miranda APIs to the .net world
  • in this assembly, there is the Virtuoso.Miranda.Plugins.PluginManager type (not publicly exposed) that finds, loads and initiates all the managed plugins in the <mirandaFolder>\plugins\managed folder
  • this assembly is the one you will want to reference on your plugin's compile time
  • this assembly also contains the most important type for us, developers, the Virtuoso.Mirandas.Plugins.MirandaPlugin class representing the base class for all of your plugins

Namespaces

There are many publicly visible namespaces containing key classes and many native interop helper classes making easy to access not yet wrapped parts of the Miranda API.

Key namespaces:

• Virtuoso.Miranda.Plugins
  • contains funtionality concerning the plugin fusion, maintentace, definition and construction
• Virtuoso.Miranda.Plugins.Infrastructure
  • contains all the functionality you may need to develop your plugins; provides Database, Contact List, Contact Information, Network Protocol and many other Miranda API wrappers
  • also contains some helper classes you may find useful (unmanaged-to-managed data translation services and localization helpers)
• Virtoso.Miranda.Plugins.Infrastructure.IndividualMirandaConnection
  • contains additional helper classes for plugins not managed by the Microsoft.net plugins supervisor
• Virtuoso.Miranda.Plugins.ObjectCollections
  • contains specialized object collections

Native interop namespaces:

• Virtuoso.Miranda.Plugins.Native
  • contains types you may use when you need to directly interface with Miranda APIs; provides you with unmanaged memory, string and struct handles

Classes

There are several classes representing the Miranda API wrappers for Database, Contact List and many other aspects of Miranda API model.

Key classes:

• Plugin definition/construction classes

  • Virtuoso.Miranda.Plugins namespace

    • abstract MirandaPlugin
      • represents a base class for all .net plugins
      • to define a plugin, derive your class from this one, implement required abstract members and you are ready to go
      • members
        • methods
          • protected
            • void .ctor()
              • Initializes an instance of the MirandaPlugin class
            • virtual void AfterPluginInitialization()
              • executed after the first plugin initialization
              • executed only once a Midas lifetime
              • use this method to initialize your plugin after Miranda startup, for example for additional event hook-ups
              • DO NOT EXECUTE ANY TIME CONSUMING CODE IN THIS METHOD NEITHER SHOW ANY WINDOWS FORMS
            • virtual void AfterMenuItemsPopulation()
              • executed after the plugin menu items detection
              • executed only once a Midas lifetime
              • use this method to change properties or manipulate with your plugin menu items
              • DO NOT EXECUTE ANY TIME CONSUMING CODE IN THIS METHOD NEITHER SHOW ANY WINDOWS FORMS
            • virtual void AfterPluginEnable()
              • executed right after a plugin is enabled by the user/supervisor
              • executed every time a plugin is enabled
              • DO NOT EXECUTE ANY TIME CONSUMING CODE IN THIS METHOD NEITHER SHOW ANY WINDOWS FORMS
            • virtual void BeforePluginDisable()
              • executed right before a plugin is disabled by the user/supervisor
              • use this method to unhook events or destroy service functions you created manually; events and services declared through attributes will be unhooked/destroyed automatically by the plugin supervisor
              • DO NOT EXECUTE ANY TIME CONSUMING CODE IN THIS METHOD NEITHER SHOW ANY WINDOWS FORMS
            • virtual void BeforeMirandaShutdown
              • executed right before Miranda or the plugin supervisor is shutdown
              • use this method to perform possible memory cleanup
              • DO NOT ALLOCATE NEW MEMORY NEITHER INTERFACE WITH MIRANDA THROUGH WRAPPERS OR NATIVE INTEROP FROM THIS METHOD; MIRANDA IS ABOUT TO SHUTDOWN AND MANY OF ITS APIS ARE NO LONGER AVAILABLE; USE THE BEFOREPLUGINDISABLE() METHOD INSTEAD