====== Developer Documentation ======
Please read the introduction first, it describes how to use AMIP API from different clients and from the SDK.
  * [[manual:amip#api_commands|AMIP API introduction]]

===== Accessing AMIP Variables =====
Above introduction describes how to call API Commands, but you can also access **AMIP variables** and use special non-void (returning something) functions.

==== From mIRC using DDE ====
mIRC provides special $dde variable which can be used to get results of evaluated function via DDE.
<code>
//echo -s song title: $dde(mplug,var_name)
</code>

This sample shows how to print song title in mIRC that is evaluated via AMIP's DDE server (mplug). ''%name'' AMIP variable is replaced with ''var_name''.

You can easily save the results of evaluation in mIRC script variables:

<code>
alias songinfo {
  set %songfile $dde(mPlug,var_fn)
  set %song $dde(mPlug,var_name)
}
</code>

To dump all AMIP variables you can type in mIRC:

<code>
/dde mplug dump
</code>

<note important>
You must replace **''%''** with **''var_''** in all AMIP variables to evaluate them.
</note>

To access **AMIP configuration** use ''cfg_KEY'', where ''KEY'' is the config option key. You can dump all configuation keys and their current values in mIRC using:
<code>
/dde mplug cfgdump
</code>

To change configuration you should use this API command:\\
**''setvar key value''**\\
Where ''key'' is the configuration option and ''value'' is the new value you want to set. For example to disable AMIP from mIRC:
<code>
/dde mplug setvar enabled 0
</code>
~~UP~~

==== From mIRC using Socket Transport ====
You need to [[amipdev:downloads#mirc_socket_transport|download]] and install ac_mirc.zip. You'll find complete instructions in ''readme.txt'' inside the distribution.

**ac.dll** provides a plenty of functions, the most interesting in context of this section are:

**''mexec''** -- executes AMIP command\\
**''meval''** -- evaluates AMIP variable or command and returns the string result

Old **/dde** command:
<code>
/dde mplug announce
</code>

New **/dll** command:
<code>
/dll ac mexec announce
</code>

Basically, just replace "**''/dde mplug''**" with "**''/dll ac mexec''**".

Old **$dde** command:
<code>
//echo -s song title: $dde(mplug,var_name)
</code>

New **$dll** command:
<code>
//echo -s song title: $dll(ac,meval,var_name)
</code>
~~UP~~
===== Evaluatable Functions =====
Some AMIP API functions that can be evaluated and return the value.

**format format_spec**\\
Returns now playing song details formatted according to the specified format. In mIRC can be used as ''$dde mplug format spec''.

<note important>
**mIRC limitation:**\\
Format specification cannot contain spaces. Replace all spaces with underscore ('_') char.\\
**Example:** ''$dde(mPlug,format,"np:_%name_[%min:%sec~m/%br~Kbps/%sr~KHz]")''.
</note>

**''fn idx''**\\
Returns name of the file from playlist with the specified ''idx'' index.

**''title idx''**\\
Returns song title from playlist with the specified ''idx'' index.

**formatsong "idx:format_spec"**\\
Returns song details formatted according to the specified format string for the song with ''idx'' index in the playlist. Doublequotes are necessary.

mIRC usage example:
<code>
$dde(mPlug,formatsong,"10:%name_br:%br~kbps")
</code>

Same limitations apply for **''formatsong''** as for **''format''** (can't use spaces).
\\
\\
\\
**AMIP 2.61** introduced new functions similar to **''formatsong''** and **''format''**:\\
  * **''rawformat''**\\
  * **''rawformatsong''**\\

The only difference is that these functions do not have limitations mentioned above, so that you can use spaces there and you don't have to quote strings, for example, not very convenient API call like:
<code>ac_eval("format \"%name_%4\"");</code> can be replaced for convenience with the following:
<code>ac_eval("rawformat %name %4");</code>

~~UP~~