Palm OS Programmer's Companion Volume II/1-3

←　2 節に戻る　↑1 章トップへ　4 節に進む　→

1-3 データの登録

　
たいていの場合、Exchange Manager からデータを受信しようとするアプリケーションは、受信するデータのMIMEタイプとファイル拡張子のどちらかまたは両方を登録する必要があります。そのために必要な関数は、サポートしようとする OS のバージョンによって異なります。
Palm OS 3.X では、ExgRegisterDataをコールしてパラメータを3つ渡します。アプリケーション自身のクリエータID、受信するデータ形式を識別する定数（ファイル拡張子ならexgRegExtentionID、MIMEタイプならexgRegTypeID）、MIMEタイプまたはファイル拡張子をリストにした文字列です。例えばPalm OS 3.Xでは、Palm OS SDKで作られた赤外線送受信サンプルアプリケーションは以下のようにコールしています。

ExgRegisterData(beamerCreator, 
  exgRegExtensionID, BitmapExt);

Palm OS 4.0 以降では、ExgRegisterDataは
ExgRegisterDatatypeに置き換えられています。ExgRegisterDatatypeはより多くの形式をサポートし、より多くのパラメータを使用します。クリエータID、登録するデータの形式、登録するデータを詳細に説明する文字列、を渡します。Palm OS 4.0以降では、MIMEタイプとファイル拡張子に加えて、クリエータIDとURLスキーマの登録がサポートされます。しかし、それらの新しいデータ形式を登録することは一般的ではありません。クリエータIDを登録するようなケースについてはデフォルトアプリケーションの設定?を、URLを登録するようなケースについては[[URLの要求を参照して下さい。
ExgRegisterDatatypeには更に2つのパラメータを渡さなければいけません.。それは、受信のために登録しようとしているデータについて説明する文字列と、他のオブジェクトの一部として送信されたときにそのデータを直接受信するかどうかを示すフラグ、です。特定の状況では、渡したパラメータに含まれる説明文字列がExchange ダイアログに表示されます。フラグについては、ラップされていないデータを受信するための登録?セクションで説明します。
例えば、Palm OS 4.0では、Palm OS SDKで作られた赤外線送受信サンプルアプリケーションは以下のようにコールしています。

ExgRegisterDatatype(beamerCreator, 
  exgRegExtensionID, BitmapExt, "bitmap", 0);

一般的な登録のガイドライン

データ登録の歳は、以下のガイドラインに従ってください。

• できる限り早く登録する

アプリケーションのインストール後いつでもデータを受信できるようにするなら、sysAppLaunchCmdSyncNotify起動コードへの反応としてExgRegisterDataかExgRegisterDatatypeをコールします。この起動コードは、アプリケーションの最初のインストール時とHotSyncによりアプリケーションのデータベースが更新されるときに、アプリケーションに対して送信されます。

• どちらかを選べるなら、自作のデータフォーマットよりも規格化されたフォーマットを使用する
• Palm OS 4.0以降では、同じデータ形式を複数のアプリケーションで受信するよう登録することができます。デフォルトアプリケーションの設定?セクションで詳しく説明します。
• ファイル拡張子の登録時、ピリオド( . )を拡張子の一部に含めないこと（"TXT"→○ / ".TXT"→×）
• 複数のMIMEタイプやファイル拡張子を登録するとき、多重コールをしないこと

かわりに、全てのファイル拡張子に対して1つのコール、全てのMIMEタイプに対して1つのコール、として下さい。ファイル拡張子を含む単一の文字列またはタブ文字( \t )で分割されたMIME形式を渡します。例えば、以下のコールは二つのファイル拡張子（TXT と DOC）を登録します。

ExgRegisterData(myCreator, exgRegExtensionID,
"TXT\tDOC", "plain text", 0);

• description パラメータはオプションです。この章にて後ほどプレビューの表示?で説明するプレビューモードを実装するなら、descriptionパラメータを設定する必要はありません。が、設定することを強く勧めます。

デフォルトアプリケーションの設定

Palm OS 4.0以降では同一のデータ形式を複数のアプリケーションに登録できるため、Exchange manager は特定のデータ形式オブジェクトを受信する際にデフォルトアプリケーションという考え方をサポートしています。デフォルトアプリケーションを設定するには、ExgSetDefaultApplication 関数をコールします。登録時のデータ形式ごとに1つのデフォルトアプリケーションを設定します。Palm OS 3.X では同一のデータ形式を複数のアプリケーションを登録することはできません。
vCard オブジェクトを受信するPalm OS 4.0デバイスがあり、そのデバイスではvCardを受信するアプリケーションが3つ登録されている、と仮定します。Exchange Manager はこれらのアプリケーションのいずれかがデフォルトとして割り当てられているかどうか、レジストリをチェックします。もし割り当てられていたら、デフォルトアプリケーションが vCard を受信します（Exchange Socket 構造体の target フィールドが設定されていなければ）。もし3つともデフォルトでないのなら、Exchange Manager は1つを選び、そのアプリケーションが全ての vCard を受信します。
PalmSource, Inc. は、ユーザーにどのアプリケーションをデフォルトとするかを選択させることを強く勧めます。そのためには、あるデータ形式を受信できるアプリケーションをユーザーに見せ、どれがデフォルトかを示し、別のものをデフォルトとして選択できる、といった機能をもつパネルを表示するべきでしょう。あるデータ形式を受信できるアプリケーションの一覧を取得するためには、ExgGetRegisteredApplications関数を使用します。現在のデフォルトを検索するには、ExgGetDefaultApplication関数を使用します。mailto URLスキームに対して iMessenger サンプルアプリケーションがこれらのタスクをどのようにこなしているか、Listing 1.2を参照してください。ソースコードはSDKに含まれています。

Listing 1.1 登録されたアプリケーションの一覧を初期化する

void PrvSetMailAppsList(Int32 listSelection) 
{ 
	ControlPtr ctl; 
	ListPtr lst; 
	UInt32 defaultID; 

	ctl = GetObjectPtr(PrefDefaultMailTrigger); 
	lst = GetObjectPtr(PrefDefaultMailList); 

	// crIDs, appCnt, appNames are all global variables.  
	// Get the list of creator IDs if we don't have it already.  
	if(!crIDs) { 
		ExgGetRegisteredApplications(&crIDs, &appCnt, &appNames, NULL,  
			exgRegSchemeID, "mailto"); 
		if(appCnt) { 
			MemHandle tmpH = SysFormPointerArrayToStrings(appNames, appCnt); 
			if(tmpH) 
				appNamesArray = MemHandleLock(tmpH); 
			else 
				return; 
		} 
		else 
			return; 
	} 

	if(appNamesArray) 
		LstSetListChoices(lst, appNamesArray, appCnt); 
	LstSetHeight(lst, appCnt < 6 ? appCnt : 6); 

	if(listSelection == -1) 
	{ 
		UInt16 i; 
		ExgGetDefaultApplication(&defaultID, exgRegSchemeID, "mailto"); 

		for(i=0;i<appCnt;i++) { 
			if(crIDs[i] == defaultID) 
				LstSetSelection(lst, i); 
		} 
	} 
	else 
		LstSetSelection(lst, listSelection); 

	CtlSetLabel(ctl, appNamesArray[LstGetSelection(lst)]); 
} 

ビルトイン Palm OS アプリケーションが受信時のデフォルトアプリケーションとして登録されているデータ形式（表1.2を参照）に対して別のアプリケーションをデフォルトにするためには、Palm OS 3.X デバイスからの赤外線通信時でも正しく受信できることを保証するために、いくつかの追加ステップを実行しなければなりません。ビルトインアプリケーションのクリエータIDを登録して、そのクリエータIDのデフォルトアプリケーションになります。
Palm OS 3.Xでは、データがビルトインアプリケーションに常に送信されるためにビルトインアプリケーションのクリエータIDを target フィールドに常に設定します。Palm OS 4.0 以降では、ある形式のデータを受信するためにビルトインアプリケーションも登録されていますが、送信時に target フィールドを設定しません。これは、もしあなたのアプリケーションがそのデータ形式に登録されておりそれがデフォルトアプリケーションであるなら、Palm OS 4.0以降からのデータは受信するが Palm OS 3.Xデバイスからのデータは（ビルトインアプリケーションに向けられているので）受信しない、ということを意味しています。
この問題を解決するために、Palm OS 4.0以降ではExgRegisterData関数で他のアプリケーションのクリエータIDを登録することがサポートされています。Listing 1.2は、vCard を受信するアプリケーションが、ユーザーに一覧（この一覧は Listing 1.1 と似たコードで初期化されるでしょう）からデフォルトを選択することを許可した後にどのようにしてデフォルトアプリケーションをセットするか、を示しています。
全てのデータ形式で、あなたのアプリケーションは他のアプリケーションに向けられたデータ（そのクリエータIDのデフォルトアプリケーションはあなたのアプリケーションであっても）を受信しないであろうことに注意してください。

Listing 1.2 vCardのデフォルトアプリケーションを設定する

UInt32 PilotMain (UInt16 cmd, void *cmdPBP, UInt16 launchFlags) 
{ 
	... 
	// Register for vCard MIME type, extension, and Address Book's creator ID.  
	// At this point, we are not the default application so we do not receive 
	// vCards. We still must register upon install so that our application  
	// appears in the preferences list when the user chooses the default  
	// application for vCards.  
	case sysAppLaunchCmdSyncNotify: 
		Char addressCreatorStr[5]; 
		 
		// Create a string from Address Book's creator ID.  
		MemMove(addressCreatorStr, sysFileCAddress, 4); 
		addressCreatorStr[4] = chrNull; 
  
		ExgRegisterDatatype(crID, exgRegTypeID, "text/x-vCard", "vCard", 0); 
		ExgRegisterDatatype(crID, exgRegExtensionID, "vcf", "vCard", 0); 
		ExgRegisterDatatype(crID, exgRegCreatorID, addressCreatorStr, NULL, 0); 
		... 
} 
  
static void PrefApply (void) 
{ 
	MemHandle h; 
	FieldType *fld; 
	ControlType *ctl; 
	UInt16 listItem; 
  
	// Set the default vCard app 
vif(appCnt && crIDs) 
	{ 
		UInt32 crID; 
		Char addressCreatorStr[5]; 
		 
		// Create a string from Address Book's creator ID.  
		MemMove(addressCreatorStr, sysFileCAddress, 4); 
		addressCreatorStr[4] = chrNull; 
		 
		listItem = LstGetSelection(GetObjectPtr(PrefDefaultAppList)); 
		crID = crIDs[listItem]; 
		ExgSetDefaultApplication(crID, exgRegTypeID, "text/x-vCard"); 
		ExgSetDefaultApplication(crID, exgRegExtensionID, "vcf"); 
		ExgSetDefaultApplication(crID, exgRegCreatorID, addressCreatorStr); 
	} 
}

ラップされていないデータを受信するための登録

Palm OS 4.0以降では、まれな状況ではありますが、他のオブジェクトに囲い込まれて送信されるデータを受信するよう登録することができます。
例えば、株価見積りアプリケーションで vStock オブジェクトを受信したいと仮定しましょう。もしデバイスが vStock オブジェクトを添付されたe-mailメッセージを受信したら、e-mailアプリケーションが vStock オブジェクトを受信するよりもあなたのアプリケーションが直接受信するように登録したいかもしれません。そのようにするなら、ExgRegisterDatatype 関数をコールして最後のパラメータとして exgUnwrap 定数を渡します。exgUnwrapと名づけられたのは、Exchange Library が受信オブジェクト（ここではe-mailメッセージ）を開封(unwrap)し、中に入っているオブジェクト（ここでは vStock オブジェクト）を直接送信するからです。
もしオブジェクトの一部として送信された特定のオブジェクトを受信するよう登録したいなら、おそらくオブジェクトそのものも受信したいでしょう。これはExgRegisterDatatype 関数の2つのコールを要求します。片方は exgUnwrap で、もう片方はそれ無しでコールされます。

ExgRegisterDatatype(myCreator,  
  exgRegExtensionID, "TXT\tDOC", "plain text",  
  0); 
ExgRegisterDatatype(myCreator,  
  exgRegExtensionID, "TXT\tDOC", "plain text",  
  exgUnwrap);

このように、ExgRegisterDatabase には4種類のコール方法があります。

• ファイル拡張子を登録するためのコール
• オブジェクトの一部として送信されたファイル拡張子を登録するためのコール
• MIMEタイプを登録するためのコール
• オブジェクトの一部として送信されたMIMEタイプを登録するためのコール

前に述べたように、ラップされていないデータを直接受信するよう登録することはまれです。E-mail アプリケーション等のアプリケーションで、複数が混ざり合ったオブジェクトを受信し開封して囲い込まれたオブジェクトを分散するためには、ローカル Exchange Library を使用するのが一般的です。ローカルでの送受信?で詳しく説明します。

←　2 節に戻る　↑1 章トップへ　4 節に進む　→