Plug-in API

THE FOLLOWING API IS WORK IN PROGRESS AND MAY NOT BE 100% FUNCTIONALLY STABLE.
THIS IS PRELIMINARY INFORMATION AND SUBJECT TO CHANGE.

The YLoader data source plugin API consists of several functions which must be exported by a plug-in dll. The C prototypes for these APIs are declared in yloader.h. These APIs can be used in applications developed in C, C++, Visual Basic, Excel or any other languages and environments that allow direct dll calls.

A data source plug-in must be implemented in a dll with the extension .ypi.

Each data source plug-in must have an unique Id (UUID).

All strings returned by various plug-in APIs consist of 8 bit characters (they can be UTF8 encoded, although international characters are not currently supported in YLoader) and are 0 terminated. The plug-in can allocate them as desired. After each string has been processed by the application, a call to freeString will be made so the plug-in can deallocate the string, if necessary.

Here are the current plug-ins APIs:

const char* getShortName();

Description: returns the address of a string containing the plug-in short name, such as "Yahoo". The short name will be displayed on the main window.
Arguments: none
Return value: the plug-in short name.

const char* getName();

Description: returns the address of a string containing the plug-in name, such as "Yahoo Data Source". The name will be displayed in the Plugin Settings window
Arguments: none
Return value: the plug-in name

const char* getDescription();

Description: returns the address of a string containing the plug-in description, such as "Downloads free quotes from the Yahoo Finance site". The name will be displayed in the Plugin Settings window properties
Arguments: none
Return value: the plug-in description

const char* getId();

Description: returns the address of a string containing the plug-in unique Id as a UUID, such as "2987B033-E5E4-4794-94BA-247A0955B612".
Arguments: none
Return value: the plug-in id

const char* getDeveloperName();

Description: returns the address of a string containing the developer name, such as "Tradery.com".
Arguments: none
Return value: the plug-in id

const char* getDeveloperURL();

Description: returns the address of a string containing the developer URL, such as "http://www.tradery.com". This will be shown as a clickable link in the properties area of the Plug-in settings pane
Arguments: none
Return value: the developer URL

const char* getDeveloperEmail();

Description: returns the address of a string containing the developer email, such as "info@yloader.com". This will be shown as a clickable link in the properties area of the Plug-in settings pane
Arguments: none
Return value: the developer email

const char* getVersion();

Description: returns the address of a string containing the plug-in version, such as "1.0.0.0". The version can contain up to four numeric fields, and it will be shown in the properties area of the Plug-in settings pane, and will be used when checking for updates.
Arguments: none
Return value: the plug-in version

const char* getAPIVersion();

Description: returns the address of a string containing the supported plug-in API version, such as "1.0.0.0". This version must match the API version declared in ydlib.h file as PLUGIN_API_VERSION. It will be shown in the properties area of the Plug-in settings pane, and will be used when checking for updates and will be used to verify the plug-in compatibility with newer versions of YLoader.
Arguments: none
Return value: the plug-in API version

const char* getYDataSourcePluginInfo();

Description: must return 0 for now.
Arguments: none
Return value: 0.

unsigned int getMaxConnections();

Description: returns an unsigned integer indicating the maximum number of connections supported by the plug-in. The minimum value is 1, which indicates that the plug-in does not support multi-threading.
Arguments: none
Return value: the maximum number of simultaneous connections supported.

bool getCanAdjust();

Description: returns a boolean value, indicating whether the plug-in supports adjusted data
Arguments: none
Return value: 0 if the plug-in doesn't support adjusted data, 1 or other non 0 value if it supports adjusted data.

bool getCanUnAdjust();

Description: returns a boolean value, indicating whether the plug-in supports un-adjusted data
Arguments: none
Return value: 0 if the plug-in doesn't support un-adjusted data, 1 or other non 0 value if it supports un-adjusted data.

const char* getFirstDate();

Description: returns the address of a string containing the earliest date supported by the plug-in, in the format: MM/DD/YYYY. If all dates are supported, then the returned value should be 0. Example, "1/1/1960" shows that the plug-in can't retrieve data earlier than Jan 1st 1960.
Arguments: none
Return value: 0 if the plug-in supports all dates, or a date string if it can't get data earlier than that date..

const char* getSupportedPeriods();

Description: returns the address of a string containing the supported data periods with the following format: "format_1 format2 ... format_n", where format_1, format_2, format_n are one of:
- 0 - daily
- 1 - weekly
- 2 - monthly
- 3 - quarterly
- 4 - yearly
For example, "1 2 3" shows that the plug-in supports weekly, monthly and quarterly data, while "0" shows that the plug-in supports only daily data.
Arguments: none
Return value: a string containing the supported periods

const char* getData( const char* symbol, const char* startDate, const char* endDate, Period period, bool adjusted, bool& error );

Description: returns the address of a string containing the downloaded data in csv format corresponding to the input parameters. Each bar of data will be on a different line, with lines separated by CR LF or 0x0d 0x0a. Each line will have the format: "date,open,high.low,close,volume", for example "10/01/2008,10.25,10.50,10.10,10.12,450000".
Arguments:
- const char* symbol - the symbol
- const char* startDate - the start date (or 0 if the oldest available)
- const char* endDate - the end date (or 0 if the most recent available)
- Period period - one of the Period enumeration values (0 - daily, 1 - weekly etc).
- bool adjusted - true to get adjusted data, false to get unadjusted data.
- bool& error - a reference to a boolean that will be set by the plug-in to indicate the status of the request. If the request for data succeeded, this will be set by the plug-in to false (0), if the request failed, the plug-in will set this boolean to true (1)
Return value: the data if the call succeeds, or an string indicating the nature of the error if the call fails.

void freeString( const char* str );

Description: a hint to the plug-in that YLoader no longer needs the string with the address "str", and that the plug-in can free it. The plug-in can choose any alloc/free strategy desired, as long as it doesn't lead to memory leaks, or to excessive memory usage, which can cause performance degradation.
Arguments:
- the address of a string previously passed by the plug-in to YLoader.
Return value: none