initial commit

git-svn-id: http://svn.miranda-ng.org/main/trunk@2 1316c22d-e87f-b044-9b9b-93d7a3e3ba9c

1 files changed, 162 insertions, 0 deletions

diff --git a/include/m_contactdir.h b/include/m_contactdir.h
new file mode 100644
index 0000000000..805fa27d64
--- /dev/null
+++ b/include/m_contactdir.h
@@ -0,0 +1,162 @@
+/*

+

+Miranda IM: the free IM client for Microsoft* Windows*

+

+Copyright 2000-2005 Miranda ICQ/IM project, 

+all portions of this codebase are copyrighted to the people 

+listed in contributors.txt.

+

+This program is free software; you can redistribute it and/or

+modify it under the terms of the GNU General Public License

+as published by the Free Software Foundation; either version 2

+of the License, or (at your option) any later version.

+

+This program is distributed in the hope that it will be useful,

+but WITHOUT ANY WARRANTY; without even the implied warranty of

+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

+GNU General Public License for more details.

+

+You should have received a copy of the GNU General Public License

+along with this program; if not, write to the Free Software

+Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

+*/

+

+#ifndef M_CONTACTDIR_H__

+#define M_CONTACTDIR_H__ 1

+

+/* Contactdir module was created on 2005/05/17, 0.4.0.1 

+

+   -- How you use this module as a protocol --

+   

+   On Load() Register your protocol with the setting name that stores unique IDs, example:

+   

+	if ( ContactDir_SupportExists() ) g_Atom=ContactDir_Register("ICQ", "UIN");

+	

+	This will register your protocol and walk the database looking for all contacts on PROTOCOL_NAME which have

+	a "UIN" setting and store it in memory (converting to a string as needed) You of course have to 

+	provide fallback if the services don't exist, it's an idea to keep existing code for that.

+	

+	-

+	

+	When you add a new contact via MS_DB_CONTACT_ADD, you must register it with your protocol atom too, via 

+	ContactDir_AddContact(atom, "UIN #", hContact) and when it is deleted ContactDir_RemoveContact(atom, "UIN #")

+	

+	-

+	

+	To find a contact, use ContactDir_Lookup(atom, "ICQ #") which will return the hContact.

+

+*/

+

+typedef struct {

+	int cbSize;

+	char * szProto;

+	char * szSetting;

+	HANDLE atom; 		// out arg

+} CONTACTDIRECTORYDESCRIPTOR;

+

+/*

+	wParam: 0

+	lParam: (LPARAM) &CONTACTDIRECTORYDESCRIPTOR;

+	Affect: Register a given protocol and it's setting name which contains the unique key entry. e.g. ("ICQ", "UIN")

+		and return a HANDLE for use with other lookup services.

+	Returns: 0 on success, non zero on failure -- a returned handle is in .atom

+	Note: The directory will convert dword values into string representations but will not do this for bytes or words

+		used as IDs -- the protocol has to convert the IDs itself (:

+	Note: See ContactDir_Register() for a quicker way.

+	*** WARNING ***: This service does not expect the given module name to have registered as a protocol module, it

+		completely bypasses this information.

+	Version: 0.4.0.1 (2005/05/17+)

+*/

+#define MS_CONTACTDIR_REGISTER "ContactDir/Register"

+

+typedef struct {

+	int cbSize;

+	HANDLE atom;		// Atom handle from MS_CONTACTDIR_REGISTER

+	char * szID;		// in: value you wish to find (makes its own copy if needed)

+	HANDLE hContact;	// out: hContact associated with szID, if any.

+} CONTACTDIRECTORYLOOKUP;

+

+/*

+

+	wParam: 0

+	lParam: (LPARAM) &CONTACTDIRECTORYLOOKUP;

+	Affect: Given an atom and string ID, will find the associated DB hContact value

+	Returns: 0 on success, non zero on failure

+	Version: 0.4.0.1 (2005/05/17+)

+	Note: ContactDir_Lookup() helper macro might be of use.

+*/

+

+#define MS_CONTACTDIR_LOOKUP "ContactDir/Lookup"

+

+/*

+	wParam: 0

+	lParam: (LPARAM)&CONTACTDIRECTORYLOOKUP;

+	Affect: Add a contact to a protocol atom association.

+	Returns: 0 on success, non zero on failure

+	Version: 0.4.0.1 (2005/05/17+)

+	Note: You must call this when you create a contact with MS_DB_CONTACT_ADD, see  ContactDir_AddContact()

+*/

+#define MS_CONTACTDIR_ADDCONTACT "ContactDir/AddContact"

+

+/*

+	wParam: 0

+	lParam: (LPARAM)&CONTACTDIRECTORYLOOKUP;

+	Affect: Remove a contact to a protocol atom association.

+	Returns: 0 on success, non zero on failure

+	Version: 0.4.0.1 (2005/05/17+)

+	Note: see ContactDir_RemoveContact()

+*/

+#define MS_CONTACTDIR_REMOVECONTACT "ContactDir/RemoveContact"

+

+

+/* -- Helper functions -- */

+

+static int ContactDir_SupportExists(void)

+{

+	return ServiceExists(MS_CONTACTDIR_REGISTER);

+}

+

+// Only take as valid if ContactDir_SupportExists() returns true.

+static HANDLE ContactDir_Register(char * szProto, char * szSetting)

+{

+	CONTACTDIRECTORYDESCRIPTOR cd;

+	cd.cbSize=sizeof(CONTACTDIRECTORYDESCRIPTOR);

+	cd.szProto=szProto;

+	cd.szSetting=szSetting;

+	cd.atom=NULL;

+	CallService(MS_CONTACTDIR_REGISTER, 0, (LPARAM)&cd);

+	return cd.atom;

+}

+

+static __inline HANDLE ContactDir_Lookup(HANDLE atom, char * szID) 

+{

+	CONTACTDIRECTORYLOOKUP f;

+	f.cbSize=sizeof(f);

+	f.atom=atom;

+	f.szID=szID;

+	f.hContact=NULL;

+	CallService(MS_CONTACTDIR_LOOKUP, 0, (LPARAM)&f);

+	return f.hContact;

+}

+

+static __inline void ContactDir_AddContact(HANDLE atom, char * szID, HANDLE hContact)

+{

+	CONTACTDIRECTORYLOOKUP c = {0};

+	c.cbSize=sizeof(CONTACTDIRECTORYLOOKUP);		

+	c.atom=atom;

+	c.szID=szID;

+	c.hContact=hContact;

+	CallService(MS_CONTACTDIR_ADDCONTACT, 0, (LPARAM)&c);

+}

+

+static __inline void ContactDir_RemoveContact(HANDLE atom, char * szID)

+{

+	CONTACTDIRECTORYLOOKUP c = {0};

+	c.cbSize=sizeof(CONTACTDIRECTORYLOOKUP);		

+	c.atom=atom;

+	c.szID=szID;

+	c.hContact=NULL;

+	CallService(MS_CONTACTDIR_REMOVECONTACT, 0, (LPARAM)&c);

+}

+

+#endif /* M_CONTACTDIR_H__ */
\ No newline at end of file