path: root/include/delphi/m_protosvc.inc

{
Miranda IM: the free IM client for Microsoft* Windows*

Copyright 2000-2009 Miranda ICQ/IM project,
all portions of this codebase are copyrighted to the people
listed in contributors.txt.

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
}

{$IFNDEF M_PROTOSVC}
{$DEFINE M_PROTOSVC}

{ *****  Unicode Services note   ********
******************************************

Only new style protocols (Miranda 0.9+) with m_iVersion set to 2 or higher
support Unicode services documented below, all other support only ANSI.

For all other that do not support Unicode services, Miranda core will
convert Unicode to ANSI and call the appropriate service.
}

type
//  PFNAMECHAR = ^FNAMECHAR;
//#if MIRANDA_VER >= 0x0900
  FNAMECHAR = TCHAR;
//#else
//  FNAMECHAR = AnsiChar;
//#endif
  TFNAMECHAR = FNAMECHAR;

{<</
    none of these services should be used on there own (i.e. using CallService(), etc)
    hence the PS_ prefix, instead use the services exposed in m_protocols.inc

    these should be called with CallProtoService which prefixes the protocol module
    name before calling.
    -
    Deleting contacts from protocols that store the contact list on the server:
    If a contact is deleted while the protocol is online, it is expected that the
    protocol will have hooked me_db_contact_deleted and take the appropriate
    action by itself.
    If a contact is deleted while the protocol is offline, the contact list will
    display a message to the user about the problem, and set the byte setting
    "CList"/"Delete" to 1. Each time such a protocol changes status from offline
    or connecting to online the contact list will check for contacts with this
    flag set and delete them at that time. Your hook for me_db_contact_deleted
    will pick this up and everything will be good.
/>>}

const
  PFLAGNUM_1        = $1;
  PF1_IMSEND        = $00000001; // supports IM sending
  PF1_IMRECV        = $00000002; // supports IM receiving
  PF1_IM            = (PF1_IMSEND or PF1_IMRECV);
  PF1_FILESEND      = $00000010; // supports file sending
  PF1_FILERECV      = $00000020; // supports file receiving
  PF1_FILE          = (PF1_FILESEND or PF1_FILERECV);
  PF1_MODEMSGSEND   = $00000040; // supports broadcasting away messages
  PF1_MODEMSGRECV   = $00000080; // supports reading others' away messages
  PF1_MODEMSG       = (PF1_MODEMSGSEND or PF1_MODEMSGRECV);
  PF1_SERVERCLIST   = $00000100; // contact lists are stored on the server, not locally. See notes below
  PF1_AUTHREQ       = $00000200; // will get authorisation requests for some or all contacts
  PF1_VISLIST       = $00000800; // has an invisible list
  PF1_INVISLIST     = $00001000; // has a visible list for when in invisible mode
  PF1_INDIVSTATUS   = $00002000; // supports setting different status modes to each contact
  PF1_EXTENSIBLE    = $00004000; // the protocol is extensible and supports plugin-defined messages
  PF1_PEER2PEER     = $00008000; // supports direct (not server mediated) communication between clients
  PF1_NEWUSER       = $00010000; // supports creation of new user IDs
  PF1_CHAT          = $00020000; // has a realtime chat capability
  PF1_INDIVMODEMSG  = $00040000; // supports replying to a mode message request with different text depending on the contact requesting
  PF1_BASICSEARCH   = $00080000; // supports a basic user searching facility
  PF1_EXTSEARCH     = $00100000; // supports one or more protocol-specific extended search schemes
  PF1_CANRENAMEFILE = $00200000; // supports renaming of incoming files as they are transferred
  PF1_FILERESUME    = $00400000; // can resume broken file transfers, see PS_FILERESUME below
  PF1_ADDSEARCHRES  = $00800000; // can add search results to the contact list
  PF1_CONTACTSEND   = $01000000; // can send contacts to other users
  PF1_CONTACTRECV   = $02000000; // can receive contacts from other users
  PF1_CONTACT       = (PF1_CONTACTSEND or PF1_CONTACTRECV);
  PF1_CHANGEINFO    = $04000000; // can change our user information stored on server
  PF1_SEARCHBYEMAIL = $08000000; // supports a search by e-mail feature
  PF1_USERIDISEMAIL = $10000000; // set if the uniquely identifying field of the network is the e-mail address
  PF1_SEARCHBYNAME  = $20000000; // supports searching by nick/first/last names
  PF1_EXTSEARCHUI   = $40000000; // has a dialog box to allow searching all the possible fields
  PF1_NUMERICUSERID = $80000000; // the unique user IDs for this protocol are numeric

  PFLAGNUM_2     = 2;          // the status modes that the protocol supports
  PF2_ONLINE     = $00000001; // an unadorned online mode
  PF2_INVISIBLE  = $00000002;
  PF2_SHORTAWAY  = $00000004; // Away on ICQ
  PF2_LONGAWAY   = $00000008; // NA on ICQ
  PF2_LIGHTDND   = $00000010; // Occupied on ICQ
  PF2_HEAVYDND   = $00000020; // DND on ICQ
  PF2_FREECHAT   = $00000040;
  PF2_IDLE       = $00000200; //added during 0.3.4 (2004/09/13)

  PFLAGNUM_3 = 3; //the status modes that the protocol supports
                  //away-style messages for. Uses the PF2_ flags.

  PFLAGNUM_4           = 4;         // v0.3+: flag asking a protocol plugin how auths are handled
  PF4_FORCEAUTH        = $00000001; // protocol has to send auth's for things to work
  PF4_NOCUSTOMAUTH     = $00000004; // protocol can't send a custom message while asking others for auth
  PF4_SUPPORTTYPING    = $00000008; // protocol supports user is typing messages v0.3.3+
  PF4_SUPPORTIDLE      = $00000010; // protocol understands idle, added during v0.3.4+ (2004/09/13)
  PF4_AVATARS          = $00000020; // protocol has avatar support, added during v0.3.4 (2004/09/13)
  PF4_OFFLINEFILES     = $00000040; // protocols supports sending files to offline users (v0.5.2)
  PF4_IMSENDUTF        = $00000080; // protocol is able to process messages in utf-8 (v.0.7.0+)
  PF4_IMSENDOFFLINE    = $00000100; // protocol supports sending offline messages (v0.8.0+)
  PF4_INFOSETTINGSVC   = $00000200; // protocol supports user info translation services (v0.8.0+)
  PF4_NOAUTHDENYREASON = $00000400; // protocol doesn't support authorization deny reason (v0.9.0+)
  PF4_GROUPCHATFILES   = $00000800; // protocol supports sending files to group chats (v0.95.2+)
  PF4_SINGLEFILEONLY   = $00001000; // protocol supports sending files one by one only

  PFLAG_UNIQUEIDTEXT         = 100; // returns a static buffer of text describing the unique field by which this protocol identifies users (already translated), or NULL
  PFLAG_MAXCONTACTSPERPACKET = 200; // v0.1.2.2+: returns the maximum number of contacts which can be sent in a single PSS_CONTACTS. lParam=(LPARAM)hContact.
  // for PS_SETSTATUS

  LOGINERR_WRONGPASSWORD = 1;
  LOGINERR_NONETWORK     = 2;
  LOGINERR_PROXYFAILURE  = 3;
  LOGINERR_BADUSERID     = 4;
  LOGINERR_NOSERVER      = 5;
  LOGINERR_TIMEOUT       = 6;
  LOGINERR_WRONGPROTOCOL = 7;
  LOGINERR_OTHERLOCATION = 8;

  // flag for PS_ADDTOLIST

  PALF_TEMPORARY = 1; // add the contact temporarily and invisibly, just to get user info or something

  // flags for PS_GETINFO

  SGIF_MINIMAL = 1; // get only the most basic information. This should
                    // contain at least a Nick and e-mail.
  SGIF_ONOPEN  = 2; // set when the User Info form is being opened

  // for PSR_MESSAGE

  PREF_CREATEREAD =  1; // create the database event with the 'read' flag set
  PREF_RTL        =  4; // 0.5+ addition: support for right-to-left messages
  PREF_SENT       = 16; // message will be created with the DBEF_SENT flag

const
  PSR_UNICODE = 1;

type
  PPROTOSEARCHRESULT = ^TPROTOSEARCHRESULT;
  TPROTOSEARCHRESULT = record
    cbSize   : int;
    flags    : int;
    nick     : TFNAMECHAR;
    firstName: TFNAMECHAR;
    lastName : TFNAMECHAR;
    email    : TFNAMECHAR;
    id       : TFNAMECHAR;
    reserved : array [0..(8*SizeOf(THANDLE) div SizeOf(dword))-1] of byte;
    // Protocols may extend this structure with extra members at will and supply
    // a larger cbSize to reflect the new information, but they must not change
    // any elements above this comment
    // The 'reserved' field is part of the basic structure, not space to
    // overwrite with protocol-specific information.
    // If modules do this, they should take steps to ensure that information
    // they put there will be retained by anyone trying to save this structure.
  end;

  PPROTORECVEVENT = ^TPROTORECVEVENT;
  TPROTORECVEVENT = record
    flags           : dword;
    timestamp       : dword;
    szMessage       : TChar;
    lParam          : LPARAM;
  end;

const
  {
    wParam : PFLAGNUM_* (see above)
    lParam : 0
    Affects: Returns a bitfield for settings corresponding to flag number, see notes
    Returns: a bitfield of supported features -- or 0 if flag_num is not supported
    Notes  : this checks what sort of things are actively supported by a protocol
             module
  }
  PS_GETCAPS = '/GetCaps';

  {
    wParam : cchName
    lParam : Pointer to a buffer to fill with human-readable name
    Affect : Get a human-readable name for the protocol, see notes
    Result : 0 on success, [non zero] on failure
    Notes  : Should be translated before being returned, cchName
             has the size of the buffer, example strings: "ICQ", "AIM"
  }
  PS_GETNAME = '/GetName';

  PLI_PROTOCOL = $1;     // An icon representing the protocol (eg the multicoloured flower for ICQ)

  PLIF_LARGE        = $0;     // Or with one of the above to get the large (32x32 by default) icon
  PLIF_SMALL        = $10000; // Or with one of the above to get the small (16x16 by default) icon
  PLIF_ICOLIB       = $20000; // the returned HICON is managed by IcoLib, DO NOT DestroyIcon() it
  PLIF_ICOLIBHANDLE = $40000; // the function will return IcoLib handle not HICON

  PS_LOADICON = '/LoadIcon';

  {
    wParam : status_mode
    lParam : Pointer to a null terminated string containing message
    Affect : Sets the status mode specific message for the user, see notes
    Returns: 0 on success, [non zero] on failure
    Notes  : This service is not available unless PF1_MODEMSGSEND is set,
             and PF1_INDIVMODEMSG is *not* set.
             -
             Protocol modules smust support lParam=NULL, it may eithere mean
             to use an empty message or (preferably) not to reply at all to
             any requests.
  }
  PS_SETAWAYMSG  = '/SetAwayMsg';

  {
    wParam : newMode from statusmodes.inc
    lParam : 0
    Affect : Change the protocol's status mode, see notes
    Returns: 0 on success, [non zero] on failure
    Notes  : Will send an ack with :
             type=ACKTYPE_SUCCESS, result=ACKRESULT_SUCCESS, hProcess=previousMode, lParam=newMode
             -
             when the change completes. This ack is sent for all changes, not
             just ones caused by calling this function.
             -
             NewMode can be ID_STATUS_CONNECTING<=newMode<ID_STATUS_CONNECTING+
             MAX_CONNECT_RETRIES to signify that it's connecting and it's the nth retry.
             -
             Protocols are initially always in offline mode, if a protocol
             doesn't support a specific status mode, it should pick the closest
             ones that it does support, and change to that.

             If a protocol has to switch from offline mode to online (or a substate
             of online, like away) then it should report any errors in the
             form of an additional ack :

             type=ACKTYPE_LOGIN, result=ACKRESULT_FAILURE, hProcess=NULL, lParam=LOGINERR_*

             SetStatus() is called when a protocol module is first loaded
             with newMode=ID_STATUS_ONLINE.
             -
             Protocols can define their own LOGINERR_* starting at $1000, see
             LOGINERR_* above
  }
  PS_SETSTATUS = '/SetStatus';

  {
    wParam : 0
    lParam : 0
    Affect : Get the status mode that a protocol is currently in, see notes
    Returns: The current status mode
    Notes  : Only protocol modules need to implement this, non network level
             protocol modules do not need to (but if you register as a protocol
             you need to, Miranda will GPF otherwise)
  }
  PS_GETSTATUS = '/GetStatus';

  {
    wParam : 0
    lParam : Pointer to a null terminated string containing an ID to search for
    Affect : Send a basic search request, see notes
    Returns: A handle to the search request or NULL(0) on failure
    Notes  : All protocols identify users uniquely by a single field
             this service will search by that field.
             -
             All search replies (even protocol-spec extended searches)
             are replied by a series of ack's,-
             -
             Result acks are a series of:
             type=ACKTYPE_SEARCH, result=ACKRESULT_DATA, lParam=Pointer to a TPROTOSEARCHRESULT structure
             -
             ending ack:
             type=ACKTYPE_SEARCH, result=ACKRESULT_SUCCESS, lParam=0
             -
             The pointers in the structure are not guaranteed to be
             valid after the ack is complete.
             -
             The structure to reply with search results can be extended
             per protocol basis (see below)

  }
  PS_BASICSEARCH  = '/BasicSearch';

  {
    wParam : 0
    lParam : Handle to window owner
    Affect : Create the advanced search dialog box, see notes
    Returns: A window handle, or NULL(0) on failure
    Notes  : this service is only available if PF1_EXTSEARCHUI capability is
             set, advanced search is very protocol-spec'd so it is left to
             the protocol itself to supply a dialog containing the options,
             this dialog should not have a titlebar and contain only search
             fields. the rest of the UI is supplied by Miranda.
             -
             The dialog should be created with CreateDialog() or it's kin
             and still be hidden when this function returns,
             -
             The dialog will be destroyed when the find/add dialog is closed
    Version: v0.1.2.1+
  }
  PS_CREATEADVSEARCHUI = '/CreateAdvSearchUI';

  {
    wParam : 0
    lParam : Handle to advanced search window handle
    Affect : Search using the advanced search dialog, see notes
    Returns: A handle or NULL(0) on failure
    Notes  : Results are returned in the same manner as PS_BASICSEARCH,
             this service is only available if PF1_EXTSEARCHUI capability is set
    Version: v0.1.2.1+
  }
  PS_SEARCHBYADVANCED = '/SearchByAdvanced';

type
  TCUSTOMSEARCHRESULTS = record
    nSize      :size_t;
    nFieldCount:int;
    szFields   :^TCHAR;
    psr        :TPROTOSEARCHRESULT;
  end;

  {
    wParam : flags
    lParam : Pointer to a TPROTOSEARCHRESULT structure
    Affect : Adds a search result to the contact list, see notes
    Returns: A handle to the new contact (TMCONTACT) or NULL(0) on failure
    Notes  : The pointer MUST be a result returned by a search function
             since there maybe extra protocol-spec data required by the protocol.
             -
             the protocol module should not allow duplicate contains to be added,
             but if such a request *is* received it should return a TMCONTACT
             to the original user,
             -
             If flags is PALF_TEMPORARY set, the contact should be added
             temorarily and invisiblely, just to get the user info (??)
             -
  }
const
  PS_ADDTOLIST = '/AddToList';

  {
    CCSDATA: Yes
    wParam : flags
    lParam : Pointer to a null terminated string
    Affect : Send an instant message
    Returns: an hProcess corresponding to an ACK which will be sent after
             the hProcess.
    Notes:  type=ACKTYPE_MESSAGE, result=ACKRESULT_SUCCESS/FAILURE,
             lParam=ansi error message or NIL
             -
             here's the deal, you must return a 'seq' from this service
             which you have to ack when the message actually get's sent,
             or send a fake ack sometime soon if you can't find out if the message
             was successfully received with the protocol that you're using.
             -
             this event is NOT added to the database automatically.
  }
  PSS_MESSAGE  = '/SendMsg';

  {
    CCSDATA: Yes
    wParam : 0
    lParam : 0
    Affect : Send a request to retrieve TMCONTACT's mode message, see notes
    Returns: a hProcess which will be ack'd later, NULL(0) on failure
    Notes  : the reply will come in a form of an ack :

             type=ACKTYPE_AWAYMSG, result=ACKRESULT_SUCCESS/FAILURE,
             lParam=pointer to a null terminated string the containing message
  }
  PSS_GETAWAYMSG = '/GetAwayMsg';

{ Proto/RecvMessage
  Copies a message from a PROTORECVEVENT event into the database
  wParam = 0 (unused)
  lParam = CCSDATA*
  Returns the result of MS_DB_EVENT_ADD
}
  PSR_MESSAGE  = '/RecvMessage';

{$ENDIF}