Documentation

[Crise 26]

With 1.0.0 Final we introduced a new feature which allows users to extend ApexDC functionality through plugins. Now as wonderful as this sounds there is a slight but... you see no plugins exists as of yet. This is where you and your creative minds kick in, we provide you with the basic information about how to create plugin and in exchange you make plugins (sounds great, doesn't it?).

I. What you can and can't do?

Those of you who know how ApexDC source code is laid out know that it has two basic parts core and gui and out of these two plugins work mostly in the core part... so no you can't create that sidebar you always wanted in apex as a plugin. However, you can do a lot on the core side as well. Here are some simple ideas that could be created as a plugin:

• More of those lovely client side chat commands, such as /winamp or /define (even to the extent of user editable list)
  
• Answering machine (for PM's)
  
• Chat/PM filtering
  
• Primitive hub link
  
• Cross hub announcer (useful for hub networks)
  

II. How does it work?

Plugins should be created as C++ dll files which implement a class derived from PluginStructure and export the following functions:

double __cdecl getVer(); // Must return API version, which is defined as API_VER in the PluginStructure.h

char* __cdecl getGuid(); // Must return unique GUID/UUID for plugin (project specific, use guidgen.exe or guidgen.com)

PluginStructure* __cdecl getObject(); // Creates plugin interface

void __cdecl freeObject(); // Frees the instance created by getObject()

There exists a sample plugin project in the ApexDC source distribution which shows how this is done in practice and we suggest anyone creating their first plugin use that as base and work from it to get all of the base code right (don't forget to change GUID).

III. PluginStructure.h what, where, how?

PluginStructure.h (located in client folder of the source distribution) is the file which defines all of the classes that are passed back and forth plugins and ApexDC... or to be more specific their interfaces, which are like skeletons that usually consists purely virtual function declarations. To put it short and simple, you do not edit this file at all even though it is the one file which makes your dll file ApexDC plugin.

Although this file is strictly read-only for plugin developers they should read it through to get a good picture about what tools the have to interact with ApexDC and what functions ApexDC calls and when. The file is well commented so it should be relatively easy to understand what everything does.

Here is a quick overview of the classes defined in this file, and their purpose:

PluginCallBackInterface: Functions that plugins can call to interact with ApexDC++, see PluginStructure::getCallBack()

UserInterface: Provides functions to get information and interact with a user.

ClientInterface: Provides functions to get information and interact with a hub.

ConnectionInterface: Provides functions to get information and interact with a client<->client connection

PluginStructure: Plugin base class, provides functions which are called by ApexDC when certain event occurs.

IV. Important Notes

Build environment

Setup used to compile plugin has same requirements as compiling ApexDC++ itself.

Plugin licensing

Plugins are automatically licensed under GNU General Public License (or GPL). Why? Because to successfully create a plugin you need a file which is part of ApexDC, and which thus is under GNU GPL and as long as your project uses GPL'ed code it is automatically required to be licensed under GPL or you have violated the licensing terms which apply to the part of code which is under GPL license.

[Freebow 0]

Sounds mighty good... Hope somebody will do an simple example how to do it...

I dont know if this can be done in this moment but would like to do an away message which could say i should be back in "20:35 (+0100)" and if that can be recalculated for the moment PM has been sent "i should be back in 1 hour 47 minutes"... That would be lovely jobely But its just an example... plugins at this time might not be done that way... instead of that some other cool things... whatever... plugins are already here \o/

[Rigor O'Mortis 1]

I don't mean to annoy anyone, but the Plugin support should really NOT have STLPort as a requirement. Personally, I consider STLPort as a useless chunk of code that uselessly bloats the ApexDC++ source code. It has a lot of drawbacks, a lot of incompatibilities and if there is one thing you shouldn't believe the makers of it, that has when they say "It should compile fine on any machine, with the standard configuration". Furthermore, it has no native 64-bit support, no native multi-core support (which you'd at least expect from something that claims to be the industry standard in multiplatform development), and it uses many deprecated symbols and syntax forms. It releases no binaries (claiming they prefer to "keep it simple for compiling", which, I have to say, is a complete and total failure on their part), and, if you take a look at the help pages, most are compiling problems, and most of them are either unsolved (some) or solved through coding mind gymnastics that I personally wouldn't go through.

There, I said it. Now I feel a lot better.

I know what I asked for isn't exactly possible, but one can dream, right ?

[Zlobomir 3]

+ it killed the horizontal view. I hate it!

[Crise 26]

+ it killed the horizontal view. I hate it!

You are wrong there Zlob, WTL update to unedited version did that... not stlport.

[Zlobomir 3]

Sorry... I hate also WTL update then... :P

[astro64 0]

Hi everybody!

Currently i am playing around with sample plugin provided in ApexDC 1.2 beta source.

I almost manage it to work. However one stupid problem remains.

In order to build plugin you need PluginAPI-Debug.lib (or -Release, whatever). Where can i get this library?

[Crise 26]

Hi everybody!

Currently i am playing around with sample plugin provided in ApexDC 1.2 beta source.

I almost manage it to work. However one stupid problem remains.

In order to build plugin you need PluginAPI-Debug.lib (or -Release, whatever). Where can i get this library?

VS generates it automatically, but in order for that to happen you must ensure that the directory where it tries to put it exists... (./plugins/lib/ or smth like that).

Also, the documentation in this topic is quite a bit outdated... as you might have noticed :)

[astro64 0]

Directories were ok .. eh .. i don't have to build entire client, do i?

Is anybody willing to explain how linker should know where to look for API implementation (qetObjectInfo, getSetting and so on), how to get plugin dll to 'import' them right from ApexDC.exe)?

[Crise 26]

Directories were ok .. eh .. i don't have to build entire client, do i?

Is anybody willing to explain how linker should know where to look for API implementation (qetObjectInfo, getSetting and so on), how to get plugin dll to 'import' them right from ApexDC.exe)?

You don't have to but, the plugin sources distributed with apex source assume you do... that is why you are having difficult time...

PluginDefs.h is under client in the src and the lib, well it is generated when the main application is built... I'd give you that file but right now I don't have one which would work for 1.2 beta release. (with next release I do intend to supply an sdk of sorts that should make the plugin building much easier for those who won't build the actual main app themselves).

[Lee 84]

New, much better, documentation will be posted soon for those who need it. ;)