[interfacekit] BRoster
- From: "Ingo Weinhold" <bonefish@xxxxxxxxxxxxxxx>
- To: "Interface Kit List" <interfacekit@xxxxxxxxxxxxx>
- Date: Tue, 18 Jun 2002 19:19:35 CEST (+0200)
Hi,
I had a closer look at the BRoster header file and annotated the
methods with hopefully useful comments -- basically functions that can
be used for the implementation and, where communication with the
registrar seems to be nessecary, a message format.
For some of the private methods I can't even guess a precise meaning,
but fortunately we aren't bound to implement any of them. For the
implementation I'd propose to start completely without private methods
and incrementally add ones when and the way they are needed. So why
have I annotated them at all=3F I think, however we do it, we will have
to provide more or less the same functionality and thus the comments
should at least help to derive a communication protcol.
Has anyone already thought about how to deal with single/multi launch
applications=3F I currently have no concrete idea. Somehow this must be
done in the (early=3F) registration phase, I guess. I'm not sure though.
Perhaps some tests will bring some more insights.
CU, Ingo
-----------------------------------------------------------------------
--
BRoster();
* =5FInitMessengers()
-----------------------------------------------------------------------
--
~BRoster();
* does nothing=3F
-----------------------------------------------------------------------
--
/* Querying for apps */
-----------------------------------------------------------------------
--
bool IsRunning(const char *mime=5Fsig) const;
bool IsRunning(entry=5Fref *ref) const;
* TeamFor()
-----------------------------------------------------------------------
--
team=5Fid TeamFor(const char *mime=5Fsig) const;
team=5Fid TeamFor(entry=5Fref *ref) const;
* GetAppInfo()
-----------------------------------------------------------------------
--
void GetAppList(BList *team=5Fid=5Flist) const;
void GetAppList(const char *sig, BList *team=5Fid=5Flist) const;
* send:
- to: fMess
- message: REG=5FGET=5FAPP=5FLIST, [ "signature": B=5FMIME=5FSTRING=5FTYPE
]
- reply: B=5FSIMPLE=5FDATA, "teams": B=5FINT32=5FTYPE[]
-----------------------------------------------------------------------
--
status=5Ft GetAppInfo(const char *sig, app=5Finfo *info) const;
status=5Ft GetAppInfo(entry=5Fref *ref, app=5Finfo *info) const;
* send:
- to: fMess
- message: REG=5FGET=5FAPP=5FINFO,
"signature": B=5FMIME=5FSTRING=5FTYPE | "ref":
B=5FREF=5FTYPE
- reply: B=5FSIMPLE=5FDATA, "info": REG=5FAPP=5FINFO=5FTYPE
-----------------------------------------------------------------------
--
status=5Ft GetRunningAppInfo(team=5Fid team, app=5Finfo *info) const;
status=5Ft GetActiveAppInfo(app=5Finfo *info) const;
* send:
- to: fMess
- message: REG=5FGET=5FRUNNING=5FAPP=5FINFO, [ "team": B=5FINT32=5FTYPE ]
- reply: B=5FSIMPLE=5FDATA, "info": REG=5FAPP=5FINFO=5FTYPE
-----------------------------------------------------------------------
--
status=5Ft FindApp(const char *mime=5Ftype, entry=5Fref *app) const;
status=5Ft FindApp(entry=5Fref *ref, entry=5Fref *app) const;
* resolve=5Fapp()
-----------------------------------------------------------------------
--
/* Launching, activating, and broadcasting to apps */
-----------------------------------------------------------------------
--
status=5Ft Broadcast(BMessage *msg) const;
status=5Ft Broadcast(BMessage *msg, BMessenger reply=5Fto) const;
* send:
- to: fMess
- message: REG=5FBROADCAST=5FMESSAGE, "message": B=5FMESSAGE=5FTYPE,
[ "reply to": B=5FMESSENGER=5FTYPE ]
- reply: B=5FSIMPLE=5FDATA, "result": B=5FINT32=5FTYPE
-----------------------------------------------------------------------
--
status=5Ft StartWatching(BMessenger target,
uint32 event=5Fmask =3D B=5FREQUEST=5FLAUNCHED
|
B=5FREQUEST=5FQUIT) const;
status=5Ft StopWatching(BMessenger target) const;
* =5FStartWatching()/=5FStopWatching()
-----------------------------------------------------------------------
--
status=5Ft ActivateApp(team=5Fid team) const;
* send:
- to: fMess
- message: REG=5FACTIVATE=5FAPP, "team": B=5FINT32=5FTYPE,
- reply: B=5FSIMPLE=5FDATA, "result": B=5FINT32=5FTYPE
-----------------------------------------------------------------------
--
status=5Ft Launch(const char *mime=5Ftype, BMessage *initial=5Fmsgs =3D
NULL,
team=5Fid *app=5Fteam =3D NULL) const;
status=5Ft Launch(const char *mime=5Ftype, BList *message=5Flist,
team=5Fid *app=5Fteam =3D NULL) const;
status=5Ft Launch(const char *mime=5Ftype, int argc, char **args,
team=5Fid *app=5Fteam =3D NULL) const;
status=5Ft Launch(const entry=5Fref *ref, const BMessage *
initial=5Fmessage =3D NULL,
team=5Fid *app=5Fteam =3D NULL) const;
status=5Ft Launch(const entry=5Fref *ref, const BList *message=5Flist,
team=5Fid *app=5Fteam =3D NULL) const;
status=5Ft Launch(const entry=5Fref *ref, int argc, const char * const *
args,
team=5Fid *app=5Fteam =3D NULL) const;
* xLaunchAppPrivate()
-----------------------------------------------------------------------
--
/* Recent document and app support */
-----------------------------------------------------------------------
--
void GetRecentDocuments(BMessage *refList, int32 maxCount,
const char *ofType =3D NULL,
const char *openedByAppSig =3D NULL) const;
void GetRecentDocuments(BMessage *refList, int32 maxCount,
const char *ofTypeList[], int32 ofTypeListCount,
const char *openedByAppSig =3D NULL) const;
* send:
- to: fMess
- message: REG=5FGET=5FRECENT=5FDOCUMENTS, "count": B=5FINT32=5FTYPE,
[ "types": B=5FMIME=5FSTRING=5FTYPE[], ]
[ "application": B=5FMIME=5FSTRING=5FTYPE ]
- reply: B=5FSIMPLE=5FDATA, "refs": B=5FREF=5FTYPE[]
-----------------------------------------------------------------------
--
void GetRecentFolders(BMessage *refList, int32 maxCount,
const char *openedByAppSig =3D NULL) const;
* send:
- to: fMess
- message: REG=5FGET=5FRECENT=5FFOLDERS, "count": B=5FINT32=5FTYPE,
[ "application": B=5FMIME=5FSTRING=5FTYPE ]
- reply: B=5FSIMPLE=5FDATA, "refs": B=5FREF=5FTYPE[]
-----------------------------------------------------------------------
--
void GetRecentApps(BMessage *refList, int32 maxCount) const;
* send:
- to: fMess
- message: REG=5FGET=5FRECENT=5FAPPS, "count": B=5FINT32=5FTYPE
- reply: B=5FSIMPLE=5FDATA, "refs": B=5FREF=5FTYPE[]
-----------------------------------------------------------------------
--
void AddToRecentDocuments(const entry=5Fref *doc,
const char *appSig =3D NULL) const;
* send:
- to: fMess
- message: REG=5FADD=5FRECENT=5FDOCUMENT, "ref": B=5FREF=5FTYPE,
[ "application": B=5FMIME=5FSTRING=5FTYPE ]
- no reply
-----------------------------------------------------------------------
--
void AddToRecentFolders(const entry=5Fref *folder,
const char *appSig =3D NULL) const;
* send:
- to: fMess
- message: REG=5FADD=5FRECENT=5FFOLDER, "ref": B=5FREF=5FTYPE,
[ "application": B=5FMIME=5FSTRING=5FTYPE ]
- no reply
-----------------------------------------------------------------------
--
/*----- Private or reserved ------------------------------*/
-----------------------------------------------------------------------
--
status=5Ft =5FStartWatching(mtarget t, BMessenger *roster=5Fmess, uint32
what,
BMessenger notify,
uint32 event=5Fmask)
const;
Sends a "start watching" message to a target that supports a
notification mechanism.
* send:
- to: fMess/fMimeMess/roster=5Fmess
- message: what, "target": B=5FMESSENGER=5FTYPE, "event mask":
B=5FUINT32=5FTYPE
- reply: B=5FSIMPLE=5FDATA, "result": B=5FINT32=5FTYPE
-----------------------------------------------------------------------
--
status=5Ft =5FStopWatching(mtarget t, BMessenger *roster=5Fmess, uint32
what,
BMessenger notify)
const;
Sends a "stop watching" message to a target that supports a
notification mechanism.
* send:
- to: fMess/fMimeMess/roster=5Fmess
- message: what, "target": B=5FMESSENGER=5FTYPE
- reply: B=5FSIMPLE=5FDATA, "result": B=5FINT32=5FTYPE
-----------------------------------------------------------------------
--
uint32 AddApplication( const char *mime=5Fsig,
entry=5Fref *ref,
uint32 flags,
team=5Fid team,
thread=5Fid thread,
port=5Fid port,
bool full=5Freg) const;
Registers the application with the roster -- if full=5Freg is false only
preliminary, whatever this means. Perhaps this reflects the two phases:
BApplication construction and BApplication::Run()=3F Or it has to do with
how is dealt with single/multi launch apps. The miminal info is {ref,
flags, team=3F}. Returns a unique token.
* send:
- to: fMess
- message: REG=5FREGISTER=5FAPP, "ref": B=5FREF=5FTYPE, "flags":
B=5FUINT32=5FTYPE,
"signature": B=5FMIME=5FSTRING=5FTYPE, "team":
B=5FINT32=5FTYPE,
"thread": B=5FINT32=5FTYPE, "port":
B=5FINT32=5FTYPE, "full":
B=5FBOOL=5FTYPE
- reply: B=5FSIMPLE=5FDATA, "token": B=5FUINT32=5FTYPE
-----------------------------------------------------------------------
--
void SetSignature(team=5Fid team, const char *mime=5Fsig) const;
Sets the application's signature in the roster.
* send:
- to: fMess
- message: REG=5FSET=5FAPP=5FSIGNATURE, "team": B=5FINT32=5FTYPE,
"signature": B=5FMIME=5FSTRING=5FTYPE
- no reply
-----------------------------------------------------------------------
--
void SetThread(team=5Fid team, thread=5Fid tid) const;
Sets the application's (main) thread in the roster.
* send:
- to: fMess
- message: REG=5FSET=5FAPP=5FTHREAD, "team": B=5FINT32=5FTYPE,
"thread": B=5FINT32=5FTYPE
- no reply
-----------------------------------------------------------------------
--
void SetThreadAndTeam(uint32 entry=5Ftoken,
thread=5Fid tid,
team=5Fid team) const;
Sets the application's (main) thread and team in the roster, when being
only pre-registered.
* send:
- to: fMess
- message: REG=5FSET=5FAPP=5FTHREAD=5FTEAM, "token": B=5FUINT32=5FTYPE,
"team": B=5FINT32=5FTYPE, "thread":
B=5FINT32=5FTYPE
- no reply
-----------------------------------------------------------------------
--
void CompleteRegistration(team=5Fid team,
thread=5Fid,
port=5Fid port)
const;
Completes the registration of a pre-registered app with the roster.
* send:
- to: fMess
- message: REG=5FCOMPLETE=5FREGISTRATION, "team": B=5FINT32=5FTYPE,
"thread": B=5FINT32=5FTYPE, "port":
B=5FINT32=5FTYPE
- no reply
-----------------------------------------------------------------------
--
bool IsAppPreRegistered( entry=5Fref *ref,
team=5Fid team,
app=5Finfo
*info) const;
Returns whether an application is pre-registered.
* send:
- to: fMess
- message: REG=5FREGISTER=5FAPP, "ref": B=5FREF=5FTYPE, "team":
B=5FINT32=5FTYPE
more info=3F
- reply: B=5FSIMPLE=5FDATA, "result": B=5FBOOL=5FTYPE
-----------------------------------------------------------------------
--
void RemovePreRegApp(uint32 entry=5Ftoken) const;
Unregisters a pre-registered app.
* send:
- to: fMess
- message: REG=5FUNREGISTER=5FAPP, "token": B=5FUINT32=5FTYPE
- no reply
-----------------------------------------------------------------------
--
void RemoveApp(team=5Fid team) const;
Unregisters an application.
* send:
- to: fMess
- message: REG=5FUNREGISTER=5FAPP, "team": B=5FINT32=5FTYPE
- no reply
-----------------------------------------------------------------------
--
status=5Ft xLaunchAppPrivate( const char *mime=5Fsig,
const
entry=5Fref *ref,
BList*
msg=5Flist,
int cargs,
char **args,
team=5Fid
*app=5Fteam) const;
Launchs an application.
* resolve=5Fapp()
* load=5Fimage()
* send=5Fto=5Frunning()=3F
Or perhaps rather send everything to the roster=3F
* send:
- to: fMess
- message: REG=5FLAUNCH=5FAPP, "file type": B=5FMIME=5FSTRING=5FTYPE,
"ref": B=5FREF=5FTYPE, [ "messages":
B=5FMESSAGE=5FTYPE[], ]
[ "args": B=5FSTRING=5FTYPE[] ]
- reply: B=5FSIMPLE=5FDATA, "team": B=5FINT32=5FTYPE
-----------------------------------------------------------------------
--
bool UpdateActiveApp(team=5Fid team) const;
=3F=3F=3F
* send:
- to: fMess
- message: REG=5FUPDATE=5FACTIVE=5FAPP, "team": B=5FINT32=5FTYPE
- reply: B=5FSIMPLE=5FDATA, "result": B=5FBOOL=5FTYPE
-----------------------------------------------------------------------
--
void SetAppFlags(team=5Fid team, uint32 flags) const;
Sets the application's flags. Probably before the app has completely
registered=3F
* send:
- to: fMess
- message: REG=5FSET=5FAPP=5FFLAGS, "team": B=5FINT32=5FTYPE, "flags":
B=5FINT32=5FTYPE
- no reply
-----------------------------------------------------------------------
--
void DumpRoster() const;
..
-----------------------------------------------------------------------
--
status=5Ft resolve=5Fapp(const char *in=5Ftype,
const entry=5Fref *ref,
entry=5Fref *app=5Fref,
char *app=5Fsig,
uint32 *app=5Fflags,
bool *was=5Fdocument) const;
Given a MIME type or an entry=5Fref the function finds out which
application is associated with it.
* translate=5Ftype()/translate=5Fref()
* BAppFileInfo::GetFlags()
-----------------------------------------------------------------------
--
status=5Ft translate=5Fref(const entry=5Fref *ref,
BMimeType *app=5Fmeta,
entry=5Fref *app=5Fref,
BFile *app=5Ffile,
char *app=5Fsig,
bool *was=5Fdocument) const;
Given an entry=5Fref the function finds out which application is
associated with it.
* NodeInfo::GetType()/sniff=5Ffile()
* translate=5Ftype()
-----------------------------------------------------------------------
--
status=5Ft translate=5Ftype(const char *mime=5Ftype,
BMimeType *meta,
entry=5Fref *app=5Fref,
BFile *app=5Ffile,
char *app=5Fsig) const;
Given a MIME type the function finds out which application is
associated with it.
* BMimeType::GetAppHint()/GetPreferredApp()/GetSupportingApps()/
GetWildcardApps()
* send:
- to: f(Mime=3F)Mess
- message: REG=5FGET=5FAPPLICATION, "signature": B=5FMIME=5FSTRING=5FTYPE
- reply: B=5FSIMPLE=5FDATA, "app ref": B=5FREF=5FTYPE
-----------------------------------------------------------------------
--
status=5Ft sniff=5Ffile(const entry=5Fref *file,
BNodeInfo *finfo,
char *mime=5Ftype) const;
Finds out which MIME type is/should be associated with a file.
* NodeInfo::GetType()
* BMimeType::GuessMimeType()
-----------------------------------------------------------------------
--
bool is=5Fwildcard(const char *sig) const;
Returns whether the supplied signature identifies a wildcard app.
* GetAppInfo() or resolve=5Fapp()
* BAppFileInfo::IsSupportedType("application/octet-stream");
-----------------------------------------------------------------------
--
status=5Ft get=5Funique=5Fsupporting=5Fapp(const BMessage *apps,
char
*out=5Fsig) const;
=3F=3F=3F
* BMimeType::GetSupportingApps()
* but what is out=5Fsig=3F
* and where is the MIME type=3F
-----------------------------------------------------------------------
--
status=5Ft get=5Frandom=5Fsupporting=5Fapp(const BMessage *apps,
char
*out=5Fsig) const;
=3F=3F=3F
* BMimeType::GetWildcardApps()
* but what is out=5Fsig=3F
-----------------------------------------------------------------------
--
char **build=5Farg=5Fvector(char **args, int *pargs,
const
entry=5Fref *app=5Fref,
const
entry=5Fref *doc=5Fref) const;
Builds an args vector from an application and a document entry=5Fref.
-----------------------------------------------------------------------
--
status=5Ft send=5Fto=5Frunning(team=5Fid team,
const entry=5Fref
*app=5Fref,
int cargs, char **args,
const BList *msg=5Flist,
const entry=5Fref *ref)
const;
Sends messages to an application (B=5FARGV=5FRECEIVED, B=5FREFS=5FRECEIVED and
arbitrary ones).
* GetRunningAppInfo()
* BMessenger::SendMessage()
-----------------------------------------------------------------------
--
void InitMessengers();
Initializes the BRoster's messengers (fMess, fMimeMess).
* fMess =3D BMessenger(<registrar port owner>,
find=5Fport("=5Froster=5Fport=5F"), 0, true);
* fMimeMess =3D BMessenger(... "main=5Fmime" ...);
or better via a protocol:
* send:
- to: fMess
- message: REG=5FGET=5FMIME=5FMESSENGER
- reply: B=5FSIMPLE=5FDATA, "messenger": B=5FMESSENGER=5FTYPE
-----------------------------------------------------------------------
--
- Follow-Ups:
- [interfacekit] Re: BRoster
- From: Ingo Weinhold
Other related posts:
- » [interfacekit] BRoster
- » [interfacekit] Re: BRoster
- » [interfacekit] Re: BRoster
- » [interfacekit] Re: BRoster
- » [interfacekit] Re: BRoster
- » [interfacekit] Re: BRoster
- [interfacekit] Re: BRoster
- From: Ingo Weinhold