Module Functions.
[API Functions]

Facilitates module manipulation and communication. More...

Functions

F2LINK std::size_t F2CALL f2_modcount ()
 Counts the number of loaded modules.
F2LINK const char *F2CALL f2_modroot (unsigned int mod)
 Retrieves a module's program directory.
F2LINK const char *F2CALL f2_moddataroot (unsigned int mod)
 Retrieves a module's data directtory.
F2LINK const char *F2CALL f2_moddocroot (unsigned int mod)
 Retrieves a module's documents directtory.
F2LINK const char *F2CALL f2_modname (unsigned int mod)
 Retrieves a module's name.
F2LINK const char *F2CALL f2_modfancyname (unsigned int mod)
 Retrieves a module's fancy name, as opposed to its "real name." This is the name set in the module's module.ini file.
F2LINK const char *F2CALL f2_modthumb (unsigned int mod)
 Retrieves a module's thumbnail image path.
F2LINK unsigned long F2CALL f2_modstate (unsigned int mod)
 Retrieves a module's state.
F2LINK void F2CALL f2_modenable (unsigned int mod, bool onoff)
 Enables or disables a module.
F2LINK unsigned int F2CALL f2_modfind (const UUID128 *uuid)
 Looks for a module by UUID.
F2LINK void F2CALL f2_modtouch (unsigned int mod)
 Sends a module a touch event.
F2LINK int F2CALL f2_modmsg (unsigned int mod, void *data)
 Sends a module a message.

Detailed Description

Facilitates module manipulation and communication.

Many of these require a module index as a parameter. To retrieve your own module index, copy it from the MOD_EVENT_START event in on_module().


Function Documentation

F2LINK std::size_t F2CALL furn2::f2_modcount (  ) 

Counts the number of loaded modules.

Returns:
The number of modules loaded.
Remarks:
Because module unloading is unsupported in F2 at the time of this writing, you can rely on the return value of f2_modcount() to remain the same for the lifetime of the program.

F2LINK const char* F2CALL furn2::f2_moddataroot ( unsigned int  mod  ) 

Retrieves a module's data directtory.

Parameters:
[in] mod The module's index.
Returns:
An absolute path to the module's data directory.
Remarks:
This is located in the per-user "Application Data" or "AppData" directory. Per-user files a module creates that it doesn't want to expose to the user go here.
Warning:
If furnarchy is running in single user mode, this directory will be the same as f2_modroot().
See also:
f2_modroot() f2_moddocroot()

F2LINK const char* F2CALL furn2::f2_moddocroot ( unsigned int  mod  ) 

Retrieves a module's documents directtory.

Parameters:
[in] mod The module's index.
Returns:
An absolute path to the module's documents directory.
Remarks:
This is located in the per-user "My Documents" or "Documents" directory. Per-user files a module creates that it wants to expose to the user go here.
Warning:
If furnarchy is running in single user mode, this directory will be the same as f2_modroot().
See also:
f2_modroot() f2_moddataroot()

F2LINK void F2CALL furn2::f2_modenable ( unsigned int  mod,
bool  onoff 
)

Enables or disables a module.

Parameters:
[in] mod The module's index.
[in] onoff true to enable a module.
Remarks:
This will trigger a MOD_EVENT_ENABLE or MOD_EVENT_DISABLE in the target module, but only if the module isn't already in that state. The enabled or disabled state is merely a suggestion for a module to restrict or unleash its full functionality. Furnarchy doesn't inhibit the module in any way just because it's in a disabled state.
See also:
f2_modstate()

F2LINK const char* F2CALL furn2::f2_modfancyname ( unsigned int  mod  ) 

Retrieves a module's fancy name, as opposed to its "real name." This is the name set in the module's module.ini file.

Parameters:
[in] mod The module's index.
Returns:
The module's fancy name.
Remarks:
The fancy name is used for purely aesthetic reasons.
See also:
f2_modname()

F2LINK unsigned int F2CALL furn2::f2_modfind ( const UUID128 *  uuid  ) 

Looks for a module by UUID.

The UUID is specified in the module's module.ini as an alternate means of locating it.

Parameters:
[in] uuid The module's UUID.
Returns:
The module's index number, or -1 if the module wasn't found.
Remarks:
A module can define a UUID if it intends to expose an interface to its neighbors (via f2_modmsg() or what have you). The UUID is the preferred method of locating such a module because the module can easily change its UUID to indicate new/incompatible interfaces.
See also:
f2_modmsg()

F2LINK int F2CALL furn2::f2_modmsg ( unsigned int  mod,
void *  data 
)

Sends a module a message.

Sends a module some module-specific data.

Parameters:
[in] mod The target module's index.
[in,out] data Module-specific data.
Returns:
The target module's response, or 0 if the target doesn't exist.
Remarks:
If f2_modmsg() seems a little vague to you, that's the point. It only provides a very general method of transporting data between modules. What the data is or means is something that must be agreed upon between the caller and the target.
See also:
f2_modfind()

F2LINK const char* F2CALL furn2::f2_modname ( unsigned int  mod  ) 

Retrieves a module's name.

This is just the module's directory name, as opposed to its "fancy name."

Parameters:
[in] mod The module's index.
Returns:
The module's name.
Remarks:
The module name can be used to reference the module via '@mod*' command line commands.
See also:
f2_modfancyname()

F2LINK const char* F2CALL furn2::f2_modroot ( unsigned int  mod  ) 

Retrieves a module's program directory.

Parameters:
[in] mod The module's index.
Returns:
An absolute path to the module's program directory.
See also:
f2_moddataroot() f2_moddocroot()

F2LINK unsigned long F2CALL furn2::f2_modstate ( unsigned int  mod  ) 

Retrieves a module's state.

Parameters:
[in] mod The module's index.
Returns:
A combination of the following flags:
  • MOD_DISABLED (mutually exclusive with MOD_ENABLED)
  • MOD_ENABLED (mutually exclusive with MOD_DISABLED)
Remarks:
Yeah, there's not much variation right now, but that could change in the future. You can modify these flags via the f2_modenable() function.
See also:
f2_modenable()

F2LINK const char* F2CALL furn2::f2_modthumb ( unsigned int  mod  ) 

Retrieves a module's thumbnail image path.

This is the path specified by the module's module.ini file, and defaults to 'thumbnail.bmp' if not.

Parameters:
[in] mod The module's index.
Returns:
An absolute path to the module's thumbnail image.
Remarks:
The module's thumbnail image should be of a common image format (jpeg, gif, tga, bmp, png, etc.) and 32x32. This is typically used by skins.

F2LINK void F2CALL furn2::f2_modtouch ( unsigned int  mod  ) 

Sends a module a touch event.

Parameters:
[in] mod The module's index.
Remarks:
The touch event has historically been a way of asking the module to expose or display more information.


Generated on Tue Jun 24 12:24:07 2008 for Furnarchy Module by  doxygen 1.5.5