Cosm API - Encoder Functions

[Cosm Logo]

Encoder Functions

CosmTransformInit
CosmTransform
CosmTransformEnd
CosmTransformEndAll

CosmTransformInit

Syntax

#include "cosm/transform.h"
s32 CosmTransformInit( cosm_TRANSFORM * transform,
  s32 (*init)( cosm_TRANSFORM *, va_list ),
  s32 (*encode)( cosm_TRANSFORM *, const void * const, u64 ),
  s32 (*end)( cosm_TRANSFORM * ),
  cosm_TRANSFORM * next_transform, ... );

Description

Setup and initialize the transform. ... depends on the transform and are fed to the transform's init, which is called by this function. If next_transform is non-NULL, then the output is fed to that transform, and many transforms will require this. See the documentation for the transform functions, which are usually provided as a single define, for more information.

init must process and copy any needed params to a struct allocated totransform->tmp_data, or if a single pointer is enough just set tmp_data. encode must process the input data and minimally pass it to the next_transform if there is one. end must finish any processing writing to the output/params and free any temprary data. See the common transforms or security functions for uses and minimal functionality of transforms.

You should always define a macro for the 3 callback functions.

Return Values

COSM_PASS on success, or a transform error code on failure.

Errors

COSM_TRANSFORM_ERROR_PARAM: Invalid parameter.
COSM_TRANSFORM_ERROR_STATE: Invalid state or functions called in the wrong order.
COSM_TRANSFORM_ERROR_MEMORY: Out of memory problem.
COSM_TRANSFORM_ERROR_FATAL: Fatal algorithm error, call ...End().
COSM_TRANSFORM_ERROR_NEXT: Invalid mode or params sent to algorithm.

Predefined transforms

COSM_BASE64_ENCODE: params = none. Output to required next_encoder is base64 encoded data, 76 columns per line.
COSM_BASE64_DECODE: params = none. Output to required next_encoder is the data decoded from base64 text input.
COSM_TRANSFORM_TO_MEMORY: params = (void *) to the start of a memory range to copy to. Output to optional next_encoder is the same as input.
COSM_TRANSFORM_TO_FILE: params = (cosm_FILE *) to an already open file to write to. Output to optional next_encoder is the same as input.
COSM_TRANSFORM_TO_NET: (cosm_NET *) to an already open netowrk connection. Output to optional next_encoder is the same as input.
COSM_TRANSFORM_TO_BUFFER: params = (cosm_BUFFER *) to an already initialized buffer, which must be a queue not a stack. Output to optional next_encoder is the same as input.

Example

  cosm_BUFFER buf;
  cosm_TRANSFORM tmp;

  CosmMemSet( &buf, sizeof( cosm_BUFFER ), 0 );
  CosmMemSet( &tmp, sizeof( cosm_TRANSFORM ), 0 );

  if ( CosmTransformInit( &tmp, COSM_TRANSFORM_TO_BUFFER,
    NULL, &buf ) != COSM_PASS )
  {
    return -1;
  }

CosmTransform

Syntax

#include "cosm/transform.h"
s32 CosmTransform( cosm_BUFFER * output, cosm_TRANSFORM * tmp,
  const void * const data, u64 length );

Description

Feed length bytes of data into the encoding routines. Any encoded data will be placed into the output buffer but may not be put into the output buffer after every call for some algorithms.

Make sure your data has been CosmSave'd before using this.

Return Values

COSM_PASS on success, or a transform error code on failure.

Errors

COSM_TRANSFORM_ERROR_PARAM: Invalid parameter.
COSM_TRANSFORM_ERROR_STATE: Invalid state or functions called in the wrong order.
COSM_TRANSFORM_ERROR_MEMORY: Out of memory problem.
COSM_TRANSFORM_ERROR_FATAL: Fatal algorithm error, call ...End().

Example

  cosm_BUFFER buf;
  cosm_TRANSFORM tmp;
  u8 data[8] = { 0, 1, 2, 3, 3, 3, 3, 4 };

  /* ... */

  if ( CosmTransform( &tmp, data, 8LL ) != COSM_PASS )
  {
    return -2;
  }

CosmTransformEnd

Syntax

#include "cosm/transform.h"
s32 CosmTransformEnd( cosm_BUFFER * output, cosm_TRANSFORM * tmp );

Description

Clear any temporary data and put the last of the encoded data into the buffer. Make sure to empty and CosmBufferFree the output buffer of your data after calling this function.

If this function fails, you must call it again. This second call will always succeed and clean up any mess.

Return Values

COSM_PASS on success, or a transform error code on failure.

Errors

COSM_TRANSFORM_ERROR_PARAM: Invalid parameter.
COSM_TRANSFORM_ERROR_STATE: Invalid state or functions called in the wrong order.
COSM_TRANSFORM_ERROR_FATAL: Fatal algorithm error, call ...End().

Example

  cosm_BUFFER buf;
  cosm_TRANSFORM tmp;

  /* ... use the transform */

  if ( CosmTransformEnd( &tmp ) != COSM_PASS )
  {
    /* something bad happened, but we're all cleaned up */

    return -3;
  }

  /* empty out the buffer */

  /* then dont forget to free it */
  CosmBufferFree( &buf );

CosmTransformEndAll

Syntax

#include "cosm/transform.h"
s32 CosmTransformEndAll( cosm_TRANSFORM * transform );

Description

Ends the transform and all transforms following it.

Return Values

COSM_PASS on success, or a transform error code on failure. Error returned will be the first error in the chain if there is one.

Errors

COSM_TRANSFORM_ERROR_STATE: Invalid state or functions called in the wrong order.
COSM_TRANSFORM_ERROR_FATAL: Fatal algorithm error.