mac_sap.h

此程式庫有許多的zigbee程式源碼

 * @brief MAC Address union
 *
 * Union of the two address types
 */
typedef union
{
    uint16 u16Short;     /**< Short address */
    MAC_ExtAddr_s sExt;  /**< Extended address */
} MAC_Addr_u;

/**
 * @ingroup g_mac_sap_addr
 * @brief MAC Address
 *
 * Full address specification
 */
typedef struct
{
    uint8      u8AddrMode;  /**< Address mode */
    uint16     u16PanId;    /**< PAN ID */
    MAC_Addr_u uAddr;       /**< Address */
} MAC_Addr_s;

/**
 * @ingroup g_mac_sap_sec
 * @brief MAC ACL entry descriptor
 *
 * ACL entry as passed over MLME, as defined in table 73 (d18)
 */
typedef struct
{
    MAC_ExtAddr_s sAclExtAddr;                                              /**< Extended address */
    uint16        u16AclShortAddr;                                          /**< Short address */
    uint16        u16AclPanId;                                              /**< PAN ID */
    uint8         u8AclSecuritySuite;                                       /**< Security suite */
    uint8         u8AclSecurityMaterialLen;                                 /**< Length of security material */
    uint8         au8AclSecurityMaterial[MAC_MAX_SECURITY_MATERIAL_LEN];    /**< Security material */
} MAC_SapAclEntry_s;

/**
 * @ingroup g_mac_sap_pib
 * @brief MAC PIB union
 *
 * Union of all PIB values as defined in table 71 (d18)
 */
typedef union
{
    uint8         u8AckWaitDuration;                            /**< macAckWaitDuration */
    uint8         u8AssociationPermit;                          /**< macAssociationPermit */
    uint8         u8AutoRequest;                                /**< macAutoRequest */
    uint8         u8BattLifeExt;                                /**< macBattLifeExt */
    uint8         u8BattLifeExtPeriods;                         /**< macBattLifeExtPeriods */
    uint8         au8BeaconPayload[MAC_MAX_BEACON_PAYLOAD_LEN]; /**< macBeaconPayload */
    uint8         u8BeaconPayloadLength;                        /**< macBeaconPayloadLength */
    uint8         u8BeaconOrder;                                /**< macBeaconOrder */
    uint32        u32BeaconTxTime;                              /**< macBeaconTxTime */
    uint8         u8Bsn;                                        /**< macBSN */
    MAC_ExtAddr_s sCoordExtAddr;                                /**< macCoordExtendedAddress */
    uint16        u16CoordShortAddr;                            /**< macCoordShortAddress */
    uint8         u8Dsn;                                        /**< macDSN */
    uint8         u8GtsPermit;                                  /**< macGTSPermit */
    uint8         u8MaxCsmaBackoffs;                            /**< macMaxCSMABackoffs */
    uint8         u8MinBe;                                      /**< macMinBE */
    uint16        u16PanId;                                     /**< macPANId */
    uint8         u8PromiscuousMode;                            /**< macPromiscuousMode */
    uint8         u8RxOnWhenIdle;                               /**< macRxOnWhenIdle */
    uint16        u16ShortAddr;                                 /**< macShortAddress */
    uint8         u8SuperframeOrder;                            /**< macSuperframeOrder */
    uint16        u16TransactionPersistenceTime;                /**< macTransactionPersistenceTime */
    /* Security attributes, as defined in table 72 (d18) */
    MAC_SapAclEntry_s sAclEntry;                                                    /**< ACL Entry table */
    uint8             u8AclEntryDescriptorSetSize;                                  /**< macACLEntryDescriptorSetSize */
    uint8             u8DefaultSecurity;                                            /**< macDefaultSecurity */
    uint8             u8AclDefaultSecurityMaterialLength;                           /**< macACLDefaultSecurityMaterialLength */
    uint8             au8DefaultSecurityMaterial[MAC_MAX_SECURITY_MATERIAL_LEN];    /**< macDefaultSecurityMaterial */
    uint8             u8DefaultSecuritySuite;                                       /**< macDefaultSecuritySuite */
    uint8             u8SecurityMode;                                               /**< macSecurityMode */
    /* New for TG4b */
    uint16 u16MaxTotalFrameTxTime;  /**< macMaxTotalFrameTxTime */
    uint8  u8ResponseWaitTime;      /**< macResponseWaitTime */
} MAC_Pib_u;

/**
 * @ingroup g_mac_sap_bcn
 * @brief PAN Descriptor
 *
 * PAN Descriptor as defined in table 41 (d18).
 * Indicates PAN parameters to a device obtained from a Beacon.
 */
typedef struct
{
    MAC_Addr_s sCoord;              /**< Coordinator address */
    uint8      u8LogicalChan;       /**< Logical channel */
    uint8      u8GtsPermit;         /**< True if beacon is from PAN coordinator which accepts GTS requests */
    uint8      u8LinkQuality;       /**< Link quality of the received beacon */
    uint8      u8SecurityUse;       /**< True if beacon received was secure */
    uint8      u8AclEntry;          /**< Security mode used in ACL entry */
    uint8      u8SecurityFailure;   /**< True if there was an error in security processing */
    uint16     u16SuperframeSpec;   /**< Superframe specification */
    uint32     u32TimeStamp;        /**< Timestamp of the received beacon */
} MAC_PanDescr_s;

/**********************/
/**** MLME Request ****/
/**********************/

/**
 * @defgroup g_mac_sap_mlme_req MLME Request objects
 * @ingroup g_mac_sap_mlme
 *
 * These are passed in a call to MAC_vHandleMlmeReqRsp.
 * Confirms to a Request will either be passed back synchronously on the function return,
 * or a special 'deferred' confirm will come back asynchronously via the
 * Deferred Confirm/Indication callback.
 * Responses have no effective confirmation of sending as they are in response to
 * an Indication; this will be indicated in the synchronous Confirm passed back.
 */

/**
 * @defgroup g_mac_sap_mlme_req_15_4 MLME Request 802.15.4 specification parameters
 * @ingroup g_mac_sap_mlme_req
 *
 * @{
 */

/**
 * @brief Structure for MLME-ASSOCIATE.request
 *
 * Association request. Use type MAC_MLME_REQ_ASSOCIATE
 */
typedef struct
{
    MAC_Addr_s sCoord;              /**< Coordinator to associate with */
    uint8      u8LogicalChan;       /**< Logical channel to associate on */
    uint8      u8Capability;        /**< Device's capability */
    uint8      u8SecurityEnable;    /**< True if security is to be used on command frames */
} MAC_MlmeReqAssociate_s;

/**
 * @brief Structure for MLME-DISASSOCIATE.request
 *
 * Disassociation request. Use type MAC_MLME_REQ_DISASSOCIATE
 * @note This is using the new proposal put forward by the ZigBee Alliance.
 * See e-mail to zigbee_interop from Karsten Vangsgaard, 20/04/04 23:27
 */
typedef struct
{
    MAC_Addr_s sAddr;               /**< Disassociating address of other end */
    uint8      u8Reason;            /**< Disassociation reason */
    uint8      u8SecurityEnable;    /**< True if security is to be used on command frames */
} MAC_MlmeReqDisassociate_s;

/**
 * @brief Structure for MLME-GET.request
 *
 * PIB get request. Use type MAC_MLME_REQ_GET
 */
typedef struct
{
    uint8 u8PibAttribute;       /**< Attribute @sa MAC_PibAttr_e */
    uint8 u8PibAttributeIndex;  /**< Index value used to specify which ACL entry to set. <b>Not part of 802.15.4</b> */
} MAC_MlmeReqGet_s;

/**
 * @brief Structure for MLME-GTS.request
 *
 * GTS request. Use type MAC_MLME_REQ_GTS
 */
typedef struct tagMAC_MlmeReqGts_s
{
    uint8 u8Characteristics;    /**< GTS characteristics */
    uint8 u8SecurityEnable;     /**< True if security is to be used on command frames */
} MAC_MlmeReqGts_s;

/**
 * @brief Structure for MLME-RESET.request
 *
 * MAC reset request. Use type MAC_MLME_REQ_RESET
 */
typedef struct
{
    uint8 u8SetDefaultPib;  /**< True if PIB is to be reset to default values */
} MAC_MlmeReqReset_s;

/**
 * @brief Structure for MLME-RX-ENABLE.request
 *
 * Receiver enable request. Use type MAC_MLME_REQ_RX_ENABLE
 */
typedef struct
{
    uint32 u32RxOnTime;     /**< Number of symbol periods from the start of the superframe before the receiver is enabled (beacon networks only) */
    uint32 u32RxOnDuration; /**< Number of symbol periods the receiver should be enabled for */
    uint8  u8DeferPermit;   /**< True if receiver enable can be deferred to the next superframe (beacon networks only) */
} MAC_MlmeReqRxEnable_s;

/**
 * @brief Structure for MLME-SCAN.request
 *
 * Scan request. Use type MAC_MLME_REQ_SCAN
 */
typedef struct tagMAC_MlmeReqScan_s
{
    uint32 u32ScanChannels; /**< Scan channels bitmap */
    uint8  u8ScanType;      /**< Scan type @sa MAC_MlmeScanType_e */
    uint8  u8ScanDuration;  /**< Scan duration */
} MAC_MlmeReqScan_s;

/**
 * @brief Structure for MLME-SET.request
 *
 * PIB set request. Use type MAC_MLME_REQ_SET
 */
typedef struct
{
    uint8     u8PibAttribute;       /**< Attribute @sa MAC_PibAttr_e */
    uint8     u8PibAttributeIndex;  /**< Index value used to specify which ACL entry to set. <b>Not part of 802.15.4</b> */
    uint16    u16Pad;               /**< Padding to show alignment */
    MAC_Pib_u uPibAttributeValue;   /**< Attribute value */
} MAC_MlmeReqSet_s;

/**
 * @brief Structure for MLME-START.request
 *
 * Superframe start request. Use type MAC_MLME_REQ_SYNC
 */
typedef struct
{
    uint16 u16PanId;            /**< The PAN ID indicated in the beacon */
    uint8  u8Channel;           /**< Channel to send beacon out on */
    uint8  u8BeaconOrder;       /**< Beacon order */
    uint8  u8SuperframeOrder;   /**< Superframe order */
    uint8  u8PanCoordinator;    /**< True if the Coordinator is a PAN Coordinator */
    uint8  u8BatteryLifeExt;    /**< True if battery life extension timings are to be used */
    uint8  u8Realignment;       /**< True if Coordinator realignment is sent when superframe parameters change */
    uint8  u8SecurityEnable;    /**< True if security is to be used on command frames */
} MAC_MlmeReqStart_s;

/**
 * @brief Structure for MLME-SYNC.request
 *
 * Superframe synchronisation request. Use type MAC_MLME_REQ_SYNC
 *
 */
typedef struct
{
    uint8  u8Channel;       /**< Channel to listen for beacon on */
    uint8  u8TrackBeacon;   /**< True if beacon is to be tracked */
} MAC_MlmeReqSync_s;

/**
 * @brief Structure for MLME-POLL.request
 *
 * Data poll request from Device. Use type MAC_MLME_REQ_POLL
 */
typedef struct
{
    MAC_Addr_s sCoord;              /**< Coordinator to poll for data */
    uint8      u8SecurityEnable;    /**< True if security is to be used on command frames */
} MAC_MlmeReqPoll_s;

/* @} */

/**
 * @defgroup g_mac_sap_mlme_req_vs MLME Request Vendor specific parameters
 * @ingroup g_mac_sap_mlme_req g_mac_sap_vs
 *
 * @{
 */

/**
 * @brief Structure for MLME-VS-EXT-ADDR.request
 *
 * Set External Address (usually constant and fixed per unit).
 * Use type MAC_MLME_REQ_VS_EXT_ADDR
 */
typedef struct
{
    MAC_ExtAddr_s sExtAddr; /**< Extended address to set */
} MAC_MlmeReqVsExtAddr_s;

/* @} */

/**********************/
/**** MLME Confirm ****/
/**********************/

/**
 * @defgroup g_mac_sap_mlme_cfm MLME Confirm objects
 * @ingroup g_mac_sap_mlme
 *
 * These come back synchronously as a returned parameter in the Request/Response call.
 * They can also be deferred and asynchronously posted via the Deferred Confirm/Indication callback.
 * The status of the actual synchronous confirm is in u8SyncCfmStatus, whereas the MAC enumerated
 * status is returned in u8Status
 */

/**
 * @defgroup g_mac_sap_mlme_cfm_15_4 MLME Confirm 802.15.4 specification parameters
 * @ingroup g_mac_sap_mlme_cfm
 *
 * @{
 */

/**
 * @brief Structure for MLME-ASSOCIATE.confirm
 *
 * Association confirm
 */
typedef struct
{
    uint8  u8Status;            /**< Status of association @sa MAC_Enum_e */
    uint8  u8Pad;               /**< Padding to show alignment */
    uint16 u16AssocShortAddr;   /**< Associated Short Address */
} MAC_MlmeCfmAssociate_s;

/**
 * @brief Structure for MLME-DISASSOCIATE.confirm
 *
 * Disassociation confirm
 */
typedef struct
{
    uint8 u8Status; /**< Status of disassociation @sa MAC_Enum_e */
} MAC_MlmeCfmDisassociate_s;

/**
 * @brief Structure for MLME-GET.confirm
 *
 * PIB get confirm. Contains the value of the attribute requested
 * @note Always returned synchronously
 */
typedef struct
{
    uint8     u8Status;             /**< Status of PIB get @sa MAC_Enum_e */
    uint8     u8PibAttribute;       /**< PIB attribute requested */
    uint16    u16Pad;               /**< Padding to show alignment */
    MAC_Pib_u uPibAttributeValue;   /**< Value of attribute */
} MAC_MlmeCfmGet_s;

/**
 * @brief Structure for MLME-GTS.confirm
 *
 * GTS confirm
 */
typedef struct
{
    uint8 u8Status;             /**< Status of GTS request @sa MAC_Enum_e */
    uint8 u8Characteristics;    /**< GTS characteristics */
} MAC_MlmeCfmGts_s;

/**
 * @brief Structure for MLME-RESET.confirm
 *
 * Reset confirm
 */
typedef struct
{
    uint8 u8Status; /**< Status of receiver enable request @sa MAC_Enum_e */
} MAC_MlmeCfmReset_s;

/**
 * @brief Structure for MLME-RX-ENABLE.confirm
 *
 * Receiver enable confirm
 */
typedef struct
{
    uint8 u8Status; /**< Status of receiver enable request @sa MAC_Enum_e */
} MAC_MlmeCfmRxEnable_s;

/**
 * @brief Union of results in Scan confirm
 *
 * Either a list of energy detect values or a list of PAN Descriptors (@sa tagMAC_PanDescr_s)
 */
typedef union
{
    uint8          au8EnergyDetect[MAC_MAX_SCAN_CHANNELS];
    MAC_PanDescr_s asPanDescr[MAC_MAX_SCAN_PAN_DESCRS];
} MAC_ScanList_u;

/**
 * @brief Structure for MLME-SCAN.confirm
 *
 * Scan confirm
 * @note Always returned synchronously
 */
typedef struct
{
    uint8          u8Status;                /**< Status of scan request @sa MAC_Enum_e */
    uint8          u8ScanType;              /**< Scan type */
    uint8          u8ResultListSize;        /**< Size of scan results list */
    uint8          u8Pad;                   /**< Padding to show alignment */
    uint32         u32UnscannedChannels;    /**< Bitmap of unscanned channels */
    MAC_ScanList_u uList;                   /**< Scan results list */
} MAC_MlmeCfmScan_s;

/**
 * @brief Structure for MLME-SET.confirm
 *
 * PIB set confirm
 * @note Always returned synchronously
 */
typedef struct
{
    uint8 u8Status;         /**< Status of PIB set request @sa MAC_Enum_e */
    uint8 u8PibAttribute;   /**< PIB attribute set */
} MAC_MlmeCfmSet_s;

/**
 * @brief Structure for MLME-START.confirm
 *
 * Superframe start confirm
 */
typedef struct
{
    uint8 u8Status; /**< Status of superframe start request @sa MAC_Enum_e */
} MAC_MlmeCfmStart_s;

/**
 * @brief Structure for MLME-POLL.confirm
 *
 * Data poll confirm