Re: [AD] docs patch

[Peter Wang <tjaden@xxxxxxxxxx>]

On 2002-07-01, Eric <ebotcazou@xxxxxxxxxx> wrote:
> +   Important: as soon as you are finished reading or writing a file using an
> +   encryption password, please remember to call packfile_password(NULL) again
> +   to return to unencrypted mode.
> 
> Why 'again' ? Is it mandatory to have called 'packfile_password(NULL)' previouly ?

'again' is redundant and may be removed.

[Your attempt]
> +  Important: as soon as you are finished reading or writing a file using an
> +  encryption password, please remember to call packfile_password(NULL)
> +  to return to unencrypted mode. This mode is mandatory in order to use
> +  other Allegro routines that operate on files, such as load_bitmap().

Sorry, I got it wrong when I was modifying the first sentence.  It
should not imply that the password must remain for the entire duration
that the encrypted packfile is open.  The current packfile password
setting [should] only affect packfiles when they are being opened.

> +   If you are using encrypted chunks, you must make sure that the password
> +   that was active at the time the chunk was opened is still active _before_
> +   closing the chunk. This is guaranteed to be true if you didn't call the
> +   packfile_password() routine in the meantime. Once you are done with
> +   encrypted chunks, call packfile_password(NULL) as explained above.
> 
> Vincent, could you explain the justification of your patch ? I suppose the
> password can't change without calling packfile_password(). Is that true ?

I attached a demo of what I think Vincent is talking about.  If you
delete the two lines marked "***", the program doesn't work, although it
should.  IMHO this is a bug in the code and not the documentation.

#include <allegro.h>

void qwrite(void)
{
    PACKFILE *f, *ff;

    f = pack_fopen("testing","w");
    packfile_password("mypassword");
    ff = pack_fopen_chunk(f,FALSE);
    packfile_password(NULL);
    pack_fputs("(this is a string)", ff);
    packfile_password("mypassword"); /* *** */
    pack_fclose_chunk(ff);
    packfile_password(NULL);	/* *** */
    pack_fclose(f);
}

void qread(void)
{
    PACKFILE *f, *ff;
    char buf[128];

    f = pack_fopen("testing","r");
    packfile_password("mypassword");
    ff = pack_fopen_chunk(f, FALSE);
    packfile_password(NULL);
    pack_fgets(buf, 128, f);
    pack_fclose_chunk(ff);
    pack_fclose(f);
    printf("%s\n",buf);
}

int main(void)
{
    allegro_init();
    qwrite();
    qread();
    return 0;
}

END_OF_MAIN()