Warning, /games/kmuddy/libmxp/doc/USAGE is written in an unsupported language. File is not indexed.
0001 0002 LibMXP - developers' documentation 0003 ---------------------------------- 0004 0005 The functions of the library are available by #including the libmxp.h 0006 header file. 0007 0008 #include <libmxp/libmxp.h> 0009 0010 IMPORTANT: this library implements the whole MXP parser, but you should 0011 still be consulting the MXP protocol when using this library, to ensure 0012 that you are correctly using the information supplied by this library 0013 0014 0015 Initializing the library 0016 ------------------------ 0017 0018 First of all, you need a MXP handler, created using mxpCreateHandler(). 0019 When you have it, you need to set all necessary parameters - default text 0020 properties, client version, supported features, and so on. 0021 0022 When the library is initialized, you need to decide, whether to use MXP or 0023 not for the particular connection. Since the MXP protocol doesn't require 0024 negotiation, whether MXP should be used or not, you'll need to handle this 0025 on yourself. Having MXP on all the time isn't very wise due to possible 0026 problems on MUDs that don'd support this protocol. 0027 The library provides some support for various modes of functioning; 0028 it is recommended, that these modes are presented to the user to choose 0029 what suits him best. 0030 0031 - Off: no MXP parsing, functions of the MXP library are never called 0032 - If negotiated: MXP is only used only after it has been enabled 0033 using telnet negotiation (option number 91). Afterwards, mxpSwitchToOpen 0034 function should be used to switch to OPEN mode - it is safe now. 0035 Make this the default option if you want to play safe. 0036 - Auto-detect: Here you pass the text to the MXP library straight from 0037 start, but you don't call switchToOpen - hence, the library will start 0038 in LOCKED mode. If some mode-change request is received, the library 0039 assumes that MXP is supported, and further processing is done normally. 0040 This should be the default if you want to be compatible with MUDs 0041 not supporting telnet negotiation. 0042 - Always on: In this state, call switchToOpen() immediately after creating the 0043 MXP handler. In this state, MXP will be used even if the MUD doesn't 0044 support it, which will lead to discarding of things containing the < 0045 character (beginning of a tag), and some text formatting via MXP 0046 will also be always possible. However, if the MUD doesn't strip ANSI 0047 sequences correctly, other players could force you into SECURE mode, and 0048 that's a Bad Thing (TM), unless you like things like having all the output 0049 in a tiny window, and other nice stuff :D 0050 Make this the default mode, if you want to be 100%-zMUD 0051 compatible. Not recommended though... 0052 0053 Oh, and one more thing. There are many features in MXP, that may require 0054 substantial changes in your client; it's not necessary to implement 0055 them all at once - you can start with the basic features (variables, 0056 attributes like bold/italics/..., colors and links), then advance to 0057 more complex features in next versions of your client... Or you can do it 0058 all at once - it's up to you :D 0059 0060 Available functions: 0061 -------------------- 0062 0063 MXPHANDLER mxpCreateHandler (); 0064 0065 Creates a new MXP handler, which holds state information for the parser. 0066 If your client supports multiple connections, you need to create a separate 0067 handler for each of them (provided that they use MXP, of course). 0068 0069 0070 void mxpDestroyHandler (MXPHANDLER handler); 0071 0072 Destroys a previously created MXP handler. 0073 0074 0075 void mxpProcessText (MXPHANDLER handler, const char *text); 0076 0077 Process some text with the handler. Pass the text received from the MUD 0078 to this function, and the library will parse it. You can then fetch the 0079 results using mxpNextresult and mxpHasResult. 0080 Note that you need to perform telnet option processing BEFORE passing the 0081 text to this function, to ensure that the server didn't disable MXP or 0082 something... 0083 0084 0085 mxpResult *mxpNextResult (MXPHANDLER handler); 0086 0087 Fetch next result of the processing. The mxpResult structure is documented 0088 below. 0089 0090 0091 int mxpHasResults (MXPHANDLER handler); 0092 0093 Checks whether there are any more results to fetch, returns non-zero if true. 0094 0095 0096 void mxpSwitchToOpen (MXPHANDLER handler); 0097 0098 Set default mode to OPEN. Refer to the explanation above for more information. 0099 0100 0101 void mxpSetDefaultText (MXPHANDLER handler, const char *font, int size, 0102 char _bold, char _italic, char _underline, char _strikeout, RGB fg, RGB bg); 0103 0104 Set default text attributes. The library will send you these when default 0105 text should be used. 0106 0107 0108 void mxpSetHeaderParams (MXPHANDLER handler, int which, const char *font, int si 0109 ze, char _bold, 0110 char _italic, char _underline, char _strikeout, RGB fg, RGB bg); 0111 0112 Set attributes of header 1-6 (for tags <h1>-<h6>). 0113 0114 0115 void mxpSetDefaultGaugeColor (MXPHANDLER handler, RGB color); 0116 0117 Set default color for gauges. 0118 0119 0120 void mxpSetNonProportFont (MXPHANDLER handler, const char *font); 0121 0122 Set used non-proportional font. 0123 0124 0125 void mxpSetClient (MXPHANDLER handler, const char *name, const char *version); 0126 0127 Set client name and version reported to the MUD. 0128 0129 0130 void mxpSetScreenProps (MXPHANDLER handler, int sx, int sy, int wx, int wy, 0131 int fx, int fy); 0132 0133 Screen, window and font size, used by FRAME and IMAGE tags. 0134 0135 0136 void mxpSupportsLink (MXPHANDLER handler, char supports); 0137 0138 Here you inform the library whether you support clickable links, including 0139 links that send commands. 0140 0141 0142 void mxpSupportsGauge (MXPHANDLER handler, char supports); 0143 0144 Here you inform the library whether you support gauges. 0145 0146 0147 void mxpSupportsStatus (MXPHANDLER handler, char supports); 0148 0149 Here you inform the library whether you support having variables in status bar. 0150 0151 0152 void mxpSupportsSound (MXPHANDLER handler, char supports); 0153 0154 Here you inform the library whether you support sound. 0155 0156 0157 void mxpSupportsFrame (MXPHANDLER handler, char supports); 0158 0159 Here you inform the library whether you support frames. 0160 0161 0162 void mxpSupportsImage (MXPHANDLER handler, char supports); 0163 0164 Here you inform the library whether you support images. 0165 0166 0167 void mxpSupportsRelocate (MXPHANDLER handler, char supports); 0168 0169 Here you inform the library whether you support relocating to other 0170 server/port and sending username/password on request. 0171 0172 0173 Note to mxpSupports* functions: you can set these to ON even if you don't 0174 support the feature, and you can receive requests to use a particular 0175 feature even if you say that you don't support it - all depends on whether 0176 the MUD pays attention to the supportedd features or not. 0177 Therefore, you should ignore all unsupported requests, the library will 0178 take care of the rest. 0179 0180 0181 0182 The mxpResult structure 0183 ----------------------- 0184 0185 struct mxpResult { 0186 int type; //result type 0187 void *data; //result data, contents depend on result type 0188 }; 0189 0190 The data attribute needs to be retyped to the correct type depending on type. 0191 These are documented here, refer to test/test.cpp for a practical example on 0192 how to use this. This test.cpp could also serve as a basis for your 0193 implementation in the client, you just need to replace all printf's with 0194 your displaying routines :-) 0195 0196 So... 0197 0198 test=0: 0199 nothing 0200 data is of type void* 0201 0202 test=1: 0203 text 0204 data is of type char* 0205 newlines are always sent separately 0206 0207 test=2: 0208 line tag 0209 data is of type int* 0210 0211 test=3: 0212 flag 0213 data is of type flagStruct* 0214 you may want to send some of these to the automapper, and to implement 0215 the set xxx flag to set the appropriate variable :-) Refer to MXP docs 0216 for more info 0217 0218 test=4: 0219 variable / erase variable 0220 data is of type varStruct* 0221 that variable should be created/updated/erased 0222 0223 test=5: 0224 formatting 0225 data is of type formatStruct* 0226 usemask says which of given attributes are valid and should be applied 0227 0228 test=6: 0229 URL link 0230 data is of type linkStruct* 0231 0232 test=7: 0233 Send link 0234 data is of type sendStruct* 0235 the command is to be sent to the MUD or put to the input line 0236 0237 test=8: 0238 expire 0239 data is of type char* 0240 All links with this name should expire. 0241 If data is 0, then all NAMED links should expire. 0242 0243 test=9: 0244 send this 0245 data is of type char* 0246 this text should be sent to the MUD, as is... Used to send version 0247 information and similar things 0248 0249 test=10: 0250 horizontal line 0251 data is of type void* 0252 0253 test=11: 0254 sound/music 0255 data is of type soundStruct* 0256 refer to the MSP protocol... 0257 0258 test=12: 0259 create a window 0260 data is of type windowStruct* 0261 0262 test=13: 0263 create an internal window 0264 data is of type internalWindowStruct* 0265 0266 test=14: 0267 close a window 0268 data is of type char* 0269 0270 test=15: 0271 set active window 0272 data is of type char* 0273 all further text will do to this window; 0 means main window 0274 0275 test=16: 0276 move cursor 0277 data is of type moveStruct* 0278 in the active window, move cursor to (X,Y) 0279 0280 test=17: 0281 erase text 0282 data is of type void* 0283 if data is 0, erase rest of line, otherwise erase rest of frame (cursor->bottom) 0284 0285 test=18: 0286 relocate 0287 data is of type relocateStruct* 0288 relocate to new server/port 0289 0290 test=19: 0291 send username/password 0292 data is of type void* 0293 if data is non-zero, send username, otherwise send password 0294 0295 test=20: 0296 image 0297 data is of type imageStruct* 0298 0299 test=21: 0300 image map 0301 data is of type char* 0302 clickable image map; will be immediately followed by the image (20) struct 0303 commands from the image map are sent to the MUD as name?X,Y 0304 0305 test=22: 0306 gauge with some variable/maxvariable 0307 data is of type gaugeStruct* 0308 0309 test=23: 0310 status bar with some variable/maxvariable 0311 data is of type statStruct* 0312 0313 test=-1: 0314 MXP error 0315 data is of type char* 0316 0317 test=-2: 0318 MXP warning 0319 data is of type char* 0320 0321 0322 0323 That is all. 0324 0325 / Tomas Mecir 0326 kmuddy@kmuddy.net 0327