SoftAd の仕様

Version 1.11

SoftAdを組み込むと、ソフトウェアのメニューバー右端に小さな広告テキストが表示されるようになります。ユーザーがその広告をクリックすると、関連付けられたホームページがブラウザで表示されます。

動作環境

SoftAdはWindows 98/Me/2000/XPまたはその上位互換OSで動作します。SoftAdを組み込んだソフトウェアがWindows 95/NTで実行されても問題はありませんが、広告は表示されません。

64ビット版のソフトウェアにSoftAdを組み込むことはできませんのでご注意ください。

インターネットに接続された環境でソフトウェアが起動されると、SoftAdは広告を表示します。インターネットに接続されていない場合、SoftAdは何も表示せず、ソフトウェアはSoftAdを組み込んでいないのと同じ状態で実行されます。

SoftAdモジュールは、ユーザーのコンピュータを識別するためにネットワークカードのMACアドレスを取得してサーバーに送信しますが、それ以外のユーザーの個人情報等は一切取得しません。また、ユーザーのマシンにファイルやクッキー等のデータを一切残しません（下記のSA_SetMsgOut()でファイル出力を有効にした場合を除く）。レジストリも使用しません。

ソフトウェアへの組み込み方法

SoftAdはオーナー描画メニュー項目として実装されています。そのため、SoftAdを組み込むには、ソフトウェアにメニューバーが必要です。

SoftAdはDLLで提供されます。このDLLからSTDCALL規約でエクスポートされているAPI関数をソフトウェアから呼び出します。これらのAPI関数は、C/C++言語から呼び出せるほか、WindowsのAPIを直接呼び出せる任意の言語から呼び出せるはずです。

コード例

ウィンドウに「Hello World!」と表示するだけのプログラムにSoftAdを組み込む例を示します。そのとき追加するコードをこの色で示してあります。わずかな行を追加するだけでSoftAdを組み込めます。

C/C++の例（DLLを静的にリンク）	表示	ダウンロード	実行画面
C/C++の例（DLLを動的にリンク）	表示	ダウンロード	実行画面
Delphiの例	表示	ダウンロード	実行画面

Visual Basic (VB) のサンプル コードは用意していないのですが、SoftAd.dll から公開されている API を直接呼び出すことによって使用できるのではないかと思います。

コード関連の補足

SoftAdを使用する場合に呼び出さなければならない必須のAPI関数は、コード例にも示されているSA_Initialize、SA_Cleanup、SA_InitMenuItem、SA_DrawMenuItemの4つだけです。

C/C++のコード例では、SoftAd.libをリンクすることでソフトウェアの起動時に静的にDLLをロードしていますが、LoadLibrary()とGetProcAddress()を使って起動後に動的にDLLをロードすることもできます。GetProcAddress()では、各関数のアドレスを名前でなく関数の順序数で取得することもできます。その場合、各関数の順序数は、提供されたSoftAd.defファイルで確認してください。

SoftAdのすべてのAPI関数は、STDCALL呼び出し規約で作成されています。ソフトウェアをC/C++で開発している場合は、提供されたSoftAd.hをインクルードすることにより、適切な型で各API関数が宣言されます。STDCALL規約では、引数がスタックに前から積まれ、呼び出された側が引数をスタックから除去します。

SoftAd.hで各関数に付加されている「extern "C"」は、C++コンパイラ向けの属性で、関数名をC++ではなくC言語の方式で生成することを指定しています。C言語でプログラムを開発している場合、お使いのCコンパイラがこの指定を認識しないときは、「extern "C"」をすべて削除してかまいません。

APIリファレンス

int SA_Initialize( HWND hWnd, HMENU hMenu, int fc, int softId );

SoftAdシステムを初期化します。SoftAdを使用するには、最初にこの関数を呼び出す必要があります。たとえばCreateWindow()の後かWM_CREATEハンドラ内で呼び出します。この関数は通信システム（Windowsソケット）などを初期化した後、一定数の広告をSoftAdのサーバーからダウンロードします。

SA_Initialize()を呼び出した後でSA_Cleanup()を呼び出してSoftAdモジュールを終了し、再びSA_Initialize()を呼び出してSoftAdモジュール再開することもできます。ただし、SoftAdモジュールを一時停止するにはSA_SetEnable()を、広告セットを再びダウンロードするにはSA_DownloadAd()を使用することをお勧めします。

hWnd	広告を表示するメニューバーを持つウィンドウのハンドル。
hMenu	広告を表示するメニューバーのハンドル。NULLを指定すると、hWndのメインメニューが使用されます。通常はNULLでかまいません。
fc	広告用メニュー項目のメニュー識別子（言い換えると機能コード）。ソフトウェアで使用している他のメニュー項目の識別子と重ならないようにしてください。0を指定すると32123が使用されます。
softId	ソフトウェア登録時にSoftAdサイトから提供されたソフトID。ここからログインして確認できます。登録前は0を指定してください。このIDを正しく指定しなくても広告は表示されますが、それらの広告がクリックされてもお支払い料金には追加されません。
(返り値)	成功した場合は1、失敗した場合は0。

void SA_Cleanup()

SoftAdシステムをクリーンアップします。SoftAdの使用を終えた後の任意のタイミングで（通常はソフトウェアを終了する直前に）呼び出してください。実際には、この関数を呼び出さずにプログラムを終了しても問題は生じないはずですが、なるべく呼び出すようにしてください。

void SA_InitMenuItem( MEASUREITEMSTRUCT* mi )

ウィンドウプロシージャにWM_MEASUREITEMメッセージが送られてきたら、この関数を呼び出す必要があります。これにより、広告用のオーナー描画メニュー項目が初期化されます。

ソフトウェアで他にもオーナー描画項目を使用している場合は、どの項目向けのWM_MEASUREITEMなのかをmiのメンバCtlTypeおよびCtlIDで判別できます。他項目向けの mi をSA_InitMenuItem()に渡すと、単に無視されます。

mi	ウィンドウプロシージャに渡されたLPARAM引数を渡します。

void SA_DrawMenuItem( DRAWITEMSTRUCT* di )

ウィンドウプロシージャにWM_DRAWITEMメッセージが送られてきたら、この関数を呼び出す必要があります。これにより、広告用のオーナー描画メニュー項目が実際に描画されます。

ソフトウェアで他にもオーナー描画項目を使用している場合は、どの項目向けのWM_DRAWITEMなのかをdiのメンバCtlTypeおよびCtlIDで判別できます。他項目向けの di をSA_DrawMenuItem()に渡すと、単に無視されます。

di	ウィンドウプロシージャに渡されたLPARAM引数を渡します。

void SA_SetEnable( int f )

広告を表示するかどうかを切り替えます。

広告を非表示にすると、広告用メニュー項目は破棄され、ウィンドウプロシージャに（SoftAdの広告用メニュー項目に対応する）WM_DRAWITEMメッセージやWM_MEASUREITEMメッセージが送られなくなります。

f	広告を表示する場合は1、一時的に非表示にする場合は0を指定します。デフォルトは1です。

void SA_SetColor( int normal, int pointed )

広告テキストの色を設定します。色はWindowsのRGB値で指定します。

normal	通常の広告テキストの色。デフォルトは濃紺（RGB( 0x00, 0x00, 0xA0 )）です。
pointed	マウスでポイントされたときの広告テキストの色。デフォルトは水色（RGB( 0x00, 0x80, 0xFF )）です。

void SA_SetSwitchInterval( int sec )

広告テキストを切り替える間隔を指定します。管理ページで間隔を指定した場合は、そちらが優先されます。

sec	広告テキストの切り替え間隔（秒単位）。デフォルトは4です。0を指定すると切り替わらなくなります。

void SA_SetTextMaxBytes( int bytes )

表示する広告テキストの長さを制限します。

SA_Initialize()の前に呼び出すと、この制限を満たす広告だけがダウンロードされます。SA_Initialize()の後で呼び出すと、ダウンロードされている広告のうち、この制限を満たす広告だけが表示されるようになります（制限を満たす広告が1つもない場合は、1つの広告が常に表示されます）。後者の場合は、表示される広告の種類が少なくなる可能性があるため、この後にSA_DownloadAd()を呼び出すことをお勧めします。

bytes

広告テキストの最大長（バイト単位）。これより長い広告は表示されません。デフォルトは50です。

void SA_SetMsgOut( int f )

SoftAdからのメッセージをファイルに残すかどうかを指定します。主にデバッグ用のオプションです。

f	SoftAdのメッセージをファイルに記録する場合は1、記録しない場合は0。デフォルトは0です。

void SA_SwitchAd()

広告を強制的に切り替えます。

void SA_SetDownloadNum( int num )

ソフトウェア起動時にダウンロードする広告の数を指定します。この関数を呼び出さなかった場合は、サーバーに設定されているデフォルト数の広告がダウンロードされます。

この設定は、以降に呼び出すSA_Initialize()とSA_DownloadAd()でサーバーからダウンロードされる広告の数に影響します。

SoftAdは、起動時に一定数の広告をダウンロードして、以後それらを切り替えながら表示します。長時間使用されるソフトウェアでは、最初にダウンロードする広告の数をこの関数で増やすか、一定時間後にSA_DownloadAd()を呼び出して（またはSA_Cleanup()とSA_Initialize()を呼び出して）広告をダウンロードし直すことにより、表示される広告の多様性を保つことができます。

num

取り込む広告の数。

void SA_DownloadAd()

広告セットを再ダウンロードします。SA_SetDownloadNum()の説明を参照してください。

void SA_SetProxy( char* addr, int port )

SoftAdがプロキシを使用するようにします。ソフトウェアがプロキシのある環境で使用される場合は、SA_Initialize()またはSA_DownloadAd()の前にこの関数を呼び出します。

addr	プロキシのIPアドレス。"192.168.1.55" のような文字列を指定します。NULLを指定すると、プロキシの設定が解除されます。
port	プロキシのポート番号。

int SA_Version()

SoftAdのバージョン番号の100倍値を返します。たとえばV1.10なら110が返ります。

登録

SoftAdを組み込んだソフトウェアを配布する前に登録が必要です。

改版記録

SoftAd  Copyright © Tama Software Ltd.