MIM DB Handler Manual

For MIM DB Handler 0.26.0-alpha

Wudi

Copyright © 2006 Wudi Studio

2006-12-30

Abstract

MIM DB Handler is a PHP class that allows you to read or wrtie the database of Miranda IM.

Table of Contents

1. Structs
1.1. Header
1.2. Module
1.3. Contact
1.4. Settings
1.5. Event
2. Guides
2.1. Opening a database
2.2. Reading a struct
2.3. Modifying a struct
2.4. Creating a struct
2.5. Deleting a struct
Next
Chapter 1. Structs


Chapter 1. Structs

Table of Contents

1.1. Header
1.2. Module
1.3. Contact
1.4. Settings
1.5. Event
Prev |  | Next
MIM DB Handler Manual | Home | 1.1. Header


1.1. Header

Members:

array(
  'signature' => BYTE[16], // signature (Miranda ICQ DB\x00\x1A)
  'version' => DWORD, // database version (0x00000700)
  'ofsFileEnd' => DWORD, // offset of the end of file
  'slackSpace' => DWORD, // wasted space in bytes
  'contactCount' => DWORD, // number of contacts
  'ofsFirstContact' => DWORD, // offset of the first contact
  'ofsUser' => DWORD, // offset of the system contact
  'ofsFirstModule' => DWORD // offset of the first module
)

Constants:

class MimDbHandler {
  const DB_HEADER_SIGNATURE = "Miranda ICQ DB\x00\x1A";
  const DB_THIS_VERSION = 0x00000700;
}

Prev | Up | Next
Chapter 1. Structs | Home | 1.2. Module


1.2. Module

Members:

array(
  'signature' => DWORD, // struct signature (0x4DDECADE)
  'ofsNext' => DWORD, // offset of the next module
  'cbModuleName' => BYTE, // length of the module name
  /************************************************/
  'moduleName' => CHAR* // module name
)

Prev | Up | Next
1.1. Header | Home | 1.3. Contact


1.3. Contact

Members:

array(
  'signature' => DWORD, // struct signature (0x43DECADE)
  'ofsNext' => DWORD, // offset of the next contact
  'ofsFirstSettings' => DWORD, // offset of the first settings
  'eventCount' => DWORD, // number of events
  'ofsFirstEvent' => DWORD, // offset of the first event
  'ofsLastEvent' => DWORD, // offset of the last event
  'ofsFirstUnreadEvent' => DWORD, // offset of the first unread event
  'timestampFirstUnread' => DWORD // timestamp of the first
                                  // unread event
)

Prev | Up | Next
1.2. Module | Home | 1.4. Settings


1.4. Settings

Members:

array(
  'signature' => DWORD, // struct signature (0x53DECADE)
  'ofsNext' => DWORD, // offset of the next settings
  'ofsModule' => DWORD, // offset of the module
  'cbBlob' => DWORD, // length of the blob
  /************************************************/
  'settings' => MimDbHandler_Setting[], // settings that read from the blob
)

Constants:

class MimDbHandler {
  const DB_SETTINGS_GRANULARITY = 128;

  const DB_VARIANT_TYPE_DELETED = 0;
  const DB_VARIANT_TYPE_BYTE = 1;
  const DB_VARIANT_TYPE_WORD = 2;
  const DB_VARIANT_TYPE_DWORD = 4;
  const DB_VARIANT_TYPE_WCHAR = 252;
  const DB_VARIANT_TYPE_UTF8 = 253;
  const DB_VARIANT_TYPE_BLOB = 254;
  const DB_VARIANT_TYPE_ASCIIZ = 255;
}

Prev | Up | Next
1.3. Contact | Home | 1.5. Event


1.5. Event

Members:

array(
  'signature' => DWORD, // struct signature (0x45DECADE)
  'ofsPrev' => DWORD, // offset of the previous event
  'ofsNext' => DWORD, // offset of the next event
  'ofsModule' => DWORD, // offset of the module
  'timestamp' => DWORD, // timestamp of the event
  'flags' => DWORD, // the flag of the event
  'eventType' => WORD, // module-defined event type
  'cbBlob' => DWORD // length of the blob
  /************************************************/
  'blob' => BYTE* // the blob (module-defined formatting)
)

Constants:

class MimDbHandler {
  const DB_EVENT_FLAG_SENT = 2;
  const DB_EVENT_FLAG_READ = 4;
  const DB_EVENT_FLAG_RTL = 8;

  const DB_EVENT_TYPE_MESSAGE = 0;
  const DB_EVENT_TYPE_URL = 1;
  const DB_EVENT_TYPE_CONTACTS = 2;
  const DB_EVENT_TYPE_ADDED = 1000;
  const DB_EVENT_TYPE_AUTHREQUEST = 1001;
  const DB_EVENT_TYPE_FILE = 1002;
}

Prev | Up | Next
1.4. Settings | Home | Chapter 2. Guides


Chapter 2. Guides

Table of Contents

2.1. Opening a database
2.2. Reading a struct
2.3. Modifying a struct
2.4. Creating a struct
2.5. Deleting a struct
Prev |  | Next
1.5. Event | Home | 2.1. Opening a database


2.1. Opening a database

bool open ( string filename [, bool readonly] )

Opens a Miranda IM database (and makes the cache for all modules).

The optional readonly parameter can be set to TRUE if you only want to read the database.

Returns TRUE on success or throws MimDbHandler_Exception on failure.

Prev | Up | Next
Chapter 2. Guides | Home | 2.2. Reading a struct


2.2. Reading a struct

array &read ( string type [, int offset [, bool full]] )

Reads a struct of type from offset offset. If offset parameter is not specified, the class will read it from current position.

When full parameter is set to FALSE, the variable-length part (such as moduleName, settings chain, and event's blob) will not be read. In this way, you can save much time when doing a search or the result need not to be cached.

See chapter Structs for information about the structs.

Returns the read struct on success, or throws MimDbHandler_Exception on failure.

Example 2.1. An example that exports all the chat history

<?php
include_once 'mimdb_handler.php';

$local_encoding = 'GBK'; // only available for database used in Miranda IM >= 0.5

$export = array();

$handler = new MimDbHandler();
$handler->open('profile.dat', TRUE);
$header =& $handler->getHeader();
$contacts =& $handler->getContacts($header['ofsFirstContact']);

$fp = fopen('export.txt', 'wb');

foreach ($contacts as $c_offset => &$contact) {
    $contents = '';
    $settings =& $handler->getSettings($contact['ofsFirstSettings']);
    $protocol = $settings['Protocol']['settings']['p']->value;
    if (isset($settings[$protocol]['settings']['Nick'])) {
        $setting_nick =& $settings[$protocol]['settings']['Nick'];
        $nickname = $setting_nick->value;
        if ($setting_nick->type == MimDbHandler::DB_VARIANT_TYPE_UTF8) {
            mb_convert_variables($local_encoding, 'UTF-8', $nickname);
        }
    } else {
        $nickname = '(no name)';
    }
    $contents = "$nickname ($protocol)\r\n\r\n";
    $events =& $handler->getEvents($contact['ofsFirstEvent']);
    foreach ($events as &$event) {
        if ($pos = strpos($event['blob'], "\x00")) {
            $text = substr($event['blob'], 0, $pos);
        } else {
            $text = $event['blob'];
        }
        $contents .= date('Y-m-d H:i:s', $event['timestamp']) . ' ';
        $contents .= ($event['flags']==MimDbHandler::DB_EVENT_FLAG_SENT) ? 'Sent' : 'Recv';
        $contents .= ": $text\r\n";
    }
    $contents .= "\r\n\r\n";
    fwrite($fp, $contents);
}

fclose($fp);

echo 'Completed.';
?>

Prev | Up | Next
2.1. Opening a database | Home | 2.3. Modifying a struct


2.3. Modifying a struct

bool update ( array struct )

Saves all changes of struct.

Returns TRUE on success or throws MimDbHandler_Exception on failure.

Prev | Up | Next
2.2. Reading a struct | Home | 2.4. Creating a struct


2.4. Creating a struct

array &create ( string type [, array args] )

Creates a new struct.

Returns the created struct on success, or throws MimDbHandler_Exception on failure.

The arguments for each struct are listed below:

header

This struct cannot be created.

module

There is no agrument for this type.

contact

There is no agrument for this type.

settings

array(
  'module' => &array, // the array of module struct passed by reference
  'contact' => &array, // the array of contact struct passed by reference
  'values' => array(
    0 => &array, // the first setting
    1 => &array, // the second one
    ...
    n => &array, // the last one
  )
)

event

array(
  'module' => &array, // the array of module struct passed by reference
  'contact' => &array, // the array of contact struct passed by reference
  'values' => array(
    'timestamp' => int, // timestamp of event
    'flags' => int, // the flag of event
    'eventType' => int, // module-defined event type
    'blob' => string // blob (module-defined formatting)
  )
)

Prev | Up | Next
2.3. Modifying a struct | Home | 2.5. Deleting a struct


2.5. Deleting a struct

bool delete ( array struct )

Deletes struct.

Returns TRUE on success or throws MimDbHandler_Exception on failure.

Prev | Up
2.4. Creating a struct | Home