Re: New member introduction

[Stuart Booth <lists@xxxxxxxxxxxxxxxx>]

On Thu, 27 Oct 2005 22:16:32 +0100, Simon McCaughey
<simonmcc@xxxxxxx> wrote:

> I used Edward's example code to fix my problem, although I stripped a
lot
>out, so it's a really simple implementation (no threads etc...)

Ohhh, you're using xFx? That'll change my answer then! I was going to
say how I implemented that area as I thought you might have rolled
your own xAP 'engine' :)

> Sorry for needing "spoon fed" but I still don't understand
the use of
>Schemas - is there a nice example somewhere that I can pick up and use
as a
>tutorial?

Schemas are essentially a related group of message types that you
might receive. They describe the format and meaning of the data in the
message. This allows different xAPplications to interoperate because
they all talk the same lingo (schema). A xAPplication might see a
message of Class=Mail.Incoming and it then knows exactly what sort of
message bodies to expect and hence how to decode it.

> I have tried a couple of things, but it doesn't behave like I would
expect.

Oh, this now makes me think that your question wasn't so much about
xAP Schema but how xFx works with them...

>xAPMessageBlock messageBlock = new
xAPMessageBlock("Serial.Comms", "
>Serial.Setup", 1);
>messageBlock.SetMandatoryNonEmptyStringField("Parity",
"odd");
>message.AddMessageBlock(messageBlock)
>That is the sort of thing I've been doing, but I suspect it's
completely
>incorrect, as I would expect it to throw some exceptions, as I haven't
>filled out all the mandatory fields

That's because a xAPMessageBlock has no schema knowledge built into
it. It's a class that understands the structure of a xAP message
common to ALL schema e.g. that there should be an equals sign between
"Parity" and "odd", and that this is a name/value pair
in a block
named Some.Thing or whatever.

So all xAPMessageBlock will do is validate that it contains a
well-formed xAP message. It does not validate the actual content of
the message for completeness or the meaning of it for validity.

In this example above you've formed xAPMessageBlock incorrectly. It's
very interesting for me to see how others use xFx as it makes me see
what is misleading, and I can see that my variable names on this CTOR
are certainly that! I've never noticed that before.

What you're after is a xAPMessage of class "Serial.Comms". Once
you
have that you can add a xAPMessageBlock whose title is
"Serial.Setup".

For example. First you create a Header for the message. This can be
either a message header or a heartbeat header, hence the different
object types here.

xAPHeader header = new xAPHeader ();

There are several parameters in a Header but it's the Class we're
interested in:

header.Class = new xAPHeaderClass ("Serial", "Comms");

Now we need a Message that contains this Header as part of it:

xAPMessage msg = new xAPMessage (header);

Next up we need a Message Block to store in the body of the message.
This is where we specify the title of the block, which comes from the
xAP Schema we're using:

xAPMessageBlock block = new xAPMessageBlock ("Serial",
"Setup");

Now we can add some parameters to this block, again from the Schema.
I'll stick to just the one.

block.Add("Port", 1);

Finally we add the Block to the Message to form a complete xAP
Message.

msg.AddMessageBlock(block);

For thrills we can output it to the console for viewing:

xAPMessageFormatInfo mfi = new xAPMessageFormatInfo ();
Console.WriteLine(msg.ToString(mfi));

This produces:

xap-header
{
v=12
Hop=1
UID=FFABCD00
Class=Serial.Comms
Source=KCSoft.TestFramework.anya
}
Serial.Setup
{
Port=1
}

You can see how the xAPHeader CTOR has filled in some default values
for the various mandatory components of the Header. That's because it
knows what is required per the xAP specification. However, according
to the Serial.Comms Schema, this message is malformed. That's because
we haven't installed all the mandatory parameters but it is still a
well-formed xAP message that any receiver should happily read. A
Schema validating xAPplication that understands the Serial.Comms
Schema would moan about this message though.

So, what are those SetMandatoryNonEmptyStringField type functions
you've seen in xFx? Well, they're actually heavily used by the classes
I've encapsulated some of the popular xAP Schema. You'll find these
implemented in the xFx xAPSchemas.DLL. This makes it harder to produce
a Serial.Comms xAP message that doesn't conform to the Schema. Not
impossible, but I find they just make using a Schema much easier as
you can talk to the data more directly without needing to convert
things.

For example, see the following code:

xAPSerialCommsMessage serial_comms_msg = new xAPSerialCommsMessage ();

xAPSerialSetupBlock setup_block = new xAPSerialSetupBlock (1);
setup_block.Baud = 1200;
setup_block.Stop = STOP_BITS.OneAndHalf;
setup_block.DataBits = 8;
setup_block.Parity = PARITY_TYPE.Even;
setup_block.FlowControl = FLOW_CONTROL.Hardware;

serial_comms_msg.AddMessageBlock(setup_block);
serial_comms_msg.AddMessageBlock(new xAPSerialSendBlock (1, "Hello,
World"));

xAPMessageFormatInfo mfi = new xAPMessageFormatInfo ();
Console.WriteLine(serial_comms_msg.ToString(mfi));

This produces this message as output:

xap-header
{
v=12
Hop=1
UID=FFABCD00
Class=Serial.Comms
Source=KCSoft.TestFramework.anya
}
Serial.Setup
{
Port=1
Baud=1200
Stop=1.5
DataBits=8
Parity=Even
Flow=Hardware
}
Serial.Send
{
Port=1
Data=Hello, World
}

A lot of the setup block parameters wouldn't be required because
they've already been initialised to some reasonable defaults. End of
the day it's just a wrapper class that knows the Serial.Comms schema
directly.

HTH?

S
--
Stuart Booth <stuart@xxxxxxx>
xAPFramework.NET - a xAP software development framework for .NET

http://www.xapautomation.org/ 
     http://www.xapframework.net/