Studio:How to define message structures: Difference between revisions

From STRIDE Wiki
Jump to navigation Jump to search
No edit summary
m (Text replace - 'Category:Unions' to 'Category:Studio:Unions')
 
(4 intermediate revisions by 2 users not shown)
Line 6: Line 6:


Below is an example:
Below is an example:
<tt>typedef struct<br>
<source lang="c">
  {<br>
typedef struct
     DEVICE_NAME,<br>
{
     INQUIRY,<br>
     DEVICE_NAME,
     SD,<br>
     INQUIRY,
     SECURITY,<br>
     SD,
     CONN, <br>
     SECURITY,
  } app_opcodes_t;</tt>
     CONN,  
} app_opcodes_t;
</source>


The corresponding message structure is as follows:
The corresponding message structure is as follows:
<tt>typedef struct<br>
<source lang="c">
  {<br>
typedef struct
     ros_hdr_t  ros_hdr;<br>
{
     vris_hdr_t  vris_hdr;<br>
     ros_hdr_t  ros_hdr;
     app_hdr_t  app_hdr;<br>
     vris_hdr_t  vris_hdr;
union<br>
     app_hdr_t  app_hdr;
      { <br>
    union
         app_name_msg_t  app_name_msg;<br>
    {  
         app_inquiry_msg_t  app_inquiry_msg;<br>
         app_name_msg_t  app_name_msg;
         app_sd_msg_t  app_sd_msg;<br>
         app_inquiry_msg_t  app_inquiry_msg;
         app_sec_msg_t  app_sec_msg;<br>
         app_sd_msg_t  app_sd_msg;
         app_conn_msg_t  app_conn_msg;<br>
         app_sec_msg_t  app_sec_msg;
      } ros_msg<br>
         app_conn_msg_t  app_conn_msg;
  } app_msg_t;</tt>
    } ros_msg;
} app_msg_t;
</source>


The first element of the union app_name_msg matches with the first enum value of DEVICE_NAME (discriminant within ros_hdr). The number and order of the discriminant values (app_opcodes_t) are the same as the union members.
The first element of the union app_name_msg matches with the first enum value of DEVICE_NAME (discriminant within ros_hdr). The number and order of the discriminant values (app_opcodes_t) are the same as the union members.


If the union within the message contains other unions (nested unions), the same rule would apply. The following example demonstrates app_sec_msg_t within ros_msg:
If the union within the message contains other unions (nested unions), the same rule would apply. The following example demonstrates app_sec_msg_t within ros_msg:
<tt>typedef enum<br>
<source lang="c">
  {<br>
typedef enum
        DISCOVERABLE_CFM,<br>
{
        CONNECTABLE_CFM,<br>
    DISCOVERABLE_CFM,
        SEC_AUTHORIZE_CFM,<br>
    CONNECTABLE_CFM,
        SEC_AUTHENTICATE_CFM,<br>
    SEC_AUTHORIZE_CFM,
        SEC_BOND_CFM,<br>
    SEC_AUTHENTICATE_CFM,
  } app_prim_sec_t;<br>
    SEC_BOND_CFM,
typedef struct<br>
} app_prim_sec_t;
{<br>
 
     app_prim_sec_t sec_msg_rsp;<br>
typedef struct
union<br>
{
{ <br>
     app_prim_sec_t sec_msg_rsp;
         discoverable_mode  discoverable_info;<br>
    union
         connectable_info_t  connectable_info;<br>
    {  
         authorize_info_t  authorize_info;<br>
         discoverable_mode  discoverable_info;
         authenticate_info_t  authenticate_info;<br>
         connectable_info_t  connectable_info;
         user_info_input_t  user_input_info;<br>
         authorize_info_t  authorize_info;
         bond_info_t  bond_info;<br>
         authenticate_info_t  authenticate_info;
        } sec_msg;<br>
         user_info_input_t  user_input_info;
} app_sec_msg_t;</tt>
         bond_info_t  bond_info;
    } sec_msg;
} app_sec_msg_t;
</source>


The above examples have the same number of discriminant values and union members. There is a one-to-one correlation between discriminant and union member. Having a discriminant for each union within nested unions decouples the unions and makes it more scalable and easier to maintain. The unions become independent of each other and can easily be extended.
The above examples have the same number of discriminant values and union members. There is a one-to-one correlation between discriminant and union member. Having a discriminant for each union within nested unions decouples the unions and makes it more scalable and easier to maintain. The unions become independent of each other and can easily be extended.
 
[[Category:Studio:Unions]]
 
[[Category:Application Notes]]

Latest revision as of 00:34, 21 August 2009

The following rules make it easier to process unions and select the active member(s) within a union or nested unions, as well as making it easier to transfer data between tasks.

  • Have a one-to-one correlation between disciminants and union members.
  • The order of enums for discriminants matches with the order of members within the union.
  • In the case of nested unions, each union should have its own discriminant.
  • Use inline data instead of pointers.

Below is an example:

typedef struct
{
    DEVICE_NAME,
    INQUIRY,
    SD,
    SECURITY,
    CONN, 
} app_opcodes_t;

The corresponding message structure is as follows:

typedef struct
{
    ros_hdr_t  ros_hdr;
    vris_hdr_t  vris_hdr;
    app_hdr_t  app_hdr;
    union
    { 
        app_name_msg_t   app_name_msg;
        app_inquiry_msg_t   app_inquiry_msg;
        app_sd_msg_t   app_sd_msg;
        app_sec_msg_t   app_sec_msg;
        app_conn_msg_t   app_conn_msg;
    } ros_msg;
} app_msg_t;

The first element of the union app_name_msg matches with the first enum value of DEVICE_NAME (discriminant within ros_hdr). The number and order of the discriminant values (app_opcodes_t) are the same as the union members.

If the union within the message contains other unions (nested unions), the same rule would apply. The following example demonstrates app_sec_msg_t within ros_msg:

typedef enum
{
    DISCOVERABLE_CFM,
    CONNECTABLE_CFM,
    SEC_AUTHORIZE_CFM,
    SEC_AUTHENTICATE_CFM,
    SEC_BOND_CFM,
} app_prim_sec_t;

typedef struct
{
    app_prim_sec_t sec_msg_rsp;
    union
    { 
        discoverable_mode   discoverable_info;
        connectable_info_t   connectable_info;
        authorize_info_t   authorize_info;
        authenticate_info_t   authenticate_info;
        user_info_input_t   user_input_info;
        bond_info_t   bond_info;
    } sec_msg;
} app_sec_msg_t;

The above examples have the same number of discriminant values and union members. There is a one-to-one correlation between discriminant and union member. Having a discriminant for each union within nested unions decouples the unions and makes it more scalable and easier to maintain. The unions become independent of each other and can easily be extended.