cleaning up
[strongswan.git] / src / charon / encoding / message.h
index 4b3f8e9..8f0be56 100644 (file)
@@ -6,7 +6,9 @@
  */
 
 /*
- * Copyright (C) 2005 Jan Hutter, Martin Willi
+ * Copyright (C) 2006 Tobias Brunner, Daniel Roethlisberger
+ * Copyright (C) 2005-2006 Martin Willi
+ * Copyright (C) 2005 Jan Hutter
  * Hochschule fuer Technik Rapperswil
  *
  * This program is free software; you can redistribute it and/or modify it
@@ -23,7 +25,9 @@
 #ifndef MESSAGE_H_
 #define MESSAGE_H_
 
-#include <types.h>
+typedef struct message_t message_t;
+
+#include <library.h>
 #include <sa/ike_sa_id.h>
 #include <network/packet.h>
 #include <encoding/payloads/ike_header.h>
@@ -32,9 +36,6 @@
 #include <crypto/crypters/crypter.h>
 #include <crypto/signers/signer.h>
 
-
-typedef struct message_t message_t;
-
 /**
  * @brief This class is used to represent an IKEv2-Message.
  *
@@ -101,6 +102,14 @@ struct message_t {
        u_int32_t (*get_message_id) (message_t *this);
        
        /**
+        * @brief Gets the initiator SPI of the message.
+        *
+        * @param this                  message_t object
+        * @return                              initiator spi of the message
+        */
+       u_int64_t (*get_initiator_spi) (message_t *this);
+
+       /**
         * @brief Gets the responder SPI of the message.
         *
         * @param this                  message_t object
@@ -111,27 +120,22 @@ struct message_t {
        /**
         * @brief Sets the IKE_SA ID of the message.
         * 
-        * @warning ike_sa_id gets cloned  internaly and 
-        * so can be destroyed afterwards.
+        * ike_sa_id gets cloned.
         *
         * @param this                  message_t object
         * @param ike_sa_id             ike_sa_id to set
         */
-       void (*set_ike_sa_id) (message_t *this,ike_sa_id_t * ike_sa_id);
+       void (*set_ike_sa_id) (message_t *this, ike_sa_id_t * ike_sa_id);
 
        /**
         * @brief Gets the IKE_SA ID of the message.
-        * 
-        * @warning The returned ike_sa_id is a clone of the internal one.
-        * So it has to be destroyed by the caller.
+        *
+        * The ike_sa_id points to the message internal id, do not modify.
         *
         * @param this                  message_t object
-        * @param ike_sa_id             pointer to ike_sa_id pointer which will be set
-        * @return                              
-        *                                              - SUCCESS
-        *                                              - FAILED if no ike_sa_id is set
+        * @return                              ike_sa_id of message
         */
-       status_t (*get_ike_sa_id) (message_t *this,ike_sa_id_t **ike_sa_id);
+       ike_sa_id_t *(*get_ike_sa_id) (message_t *this);
 
        /**
         * @brief Sets the exchange type of the message.
@@ -180,6 +184,21 @@ struct message_t {
        void (*add_payload) (message_t *this, payload_t *payload);
 
        /**
+        * @brief Build a notify payload and add it to the message.
+        * 
+        * This is a helper method to create notify messages or add
+        * notify payload to messages. The flush parameter specifies if existing
+        * payloads should get removed before appending the notify.
+        *
+        * @param this                  message_t object
+        * @param flush                 TRUE to remove existing payloads
+        * @param type                  type of the notify
+        * @param data                  a chunk of data to add to the notify, gets cloned
+        */     
+       void (*add_notify) (message_t *this, bool flush, notify_type_t type, 
+                                               chunk_t data);
+
+       /**
         * @brief Parses header of message.
         * 
         * Begins parisng of a message created via message_create_from_packet().
@@ -210,11 +229,12 @@ struct message_t {
         * @param crypter       crypter to decrypt encryption payloads
         * @param signer        signer to verifiy a message with an encryption payload
         * @return
-        *                                      - SUCCESS if header could be parsed
+        *                                      - SUCCESS if parsing successful
         *                                      - NOT_SUPPORTED if ciritcal unknown payloads found
-        *                                      - FAILED if message type is not suppported!
-        *                                      - PARSE_ERROR if corrupted/invalid data found
-        *                                      - VERIFY_ERROR if verification of some payload failed
+        *                                      - NOT_SUPPORTED if message type is not supported!
+        *                                      - PARSE_ERROR if message parsing failed
+        *                                      - VERIFY_ERROR if message verification failed (bad syntax)
+        *                                      - FAILED if integrity check failed
         *                                      - INVALID_STATE if crypter/signer not supplied, but needed
         */
        status_t (*parse_body) (message_t *this, crypter_t *crypter, signer_t *signer);
@@ -229,10 +249,12 @@ struct message_t {
         * message.
         * Crypter/signer can be omitted (by passing NULL) when no encryption 
         * payload is expected.
+        * Generation is only done once, multiple calls will just return a packet copy.
         *
         * @param this          message_t object
         * @param crypter       crypter to use when a payload must be encrypted
         * @param signer        signer to build a mac
+        * @param packet        copy of generated packet
         * @return
         *                                      - SUCCESS if packet could be generated
         *                                      - INVALID_STATE if exchange type is currently not set
@@ -297,7 +319,18 @@ struct message_t {
        iterator_t * (*get_payload_iterator) (message_t *this);
        
        /**
-        * Returns a clone of the internal stored packet_t object.
+        * @brief Find a payload of a specific type.
+        * 
+        * Returns the first occurance. 
+        *
+        * @param this          message_t object
+        * @param type          type of the payload to find
+        * @return                      payload, or NULL if no such payload found
+        */     
+       payload_t* (*get_payload) (message_t *this, payload_type_t type);
+       
+       /**
+        * @brief Returns a clone of the internal stored packet_t object.
         *
         * @param this          message_t object
         * @return                      packet_t object as clone of internal one
@@ -305,14 +338,13 @@ struct message_t {
        packet_t * (*get_packet) (message_t *this);
        
        /**
-        * Returns a clone of the internal stored packet_t data.
+        * @brief Returns a clone of the internal stored packet_t data.
         *
         * @param this          message_t object
         * @return                      clone of the internal stored packet_t data.
         */     
        chunk_t (*get_packet_data) (message_t *this);
        
-       
        /**
         * @brief Destroys a message and all including objects.
         *
@@ -355,13 +387,4 @@ message_t * message_create_from_packet(packet_t *packet);
  */
 message_t * message_create(void);
 
-/**
- * @brief Creates an message_t object of type reply containing a notify payload.
- *
- * @return message_t object
- *
- * @ingroup encoding
- */
-message_t *message_create_notify_reply(host_t *source, host_t *destination, exchange_type_t exchange_type, bool original_initiator,ike_sa_id_t *ike_sa_id,notify_message_type_t notify_type);
-
 #endif /*MESSAGE_H_*/