Open eCard

h1. Client Control Interface

The Client Control Interface is http based. The webserver of the eCard client is available only under http://localhost:24724.

h2. Activation

*URL*

@http://127.0.0.1:24727/eID-Client@

*Method*

GET

*Query*

| tcTokenURL    | The URL determines where the client can retrieve the TC Token. See TR-03112-7, section 3.2 | Mandatory | 

| ifdName       | The ifdName determines the card terminal.|  Optional[1] | 

| contextHandle | The contextHandle addresses a specific IFD. | Optional[1] | 

| slotHandle    | The slotHandle determines a connected eCard. See TR-03112-6, section 3.2.1. | Optional[1] | 

| cardType      | The cardType determines the type of card which must be selected. | Optional[1] |

*Returns*

| 200 OK                    | The refresh address is comprised in the Message Body (Hack for Mac OS Safari). |

| 303 See Other             | The Location field in the response should contain the refresh address. |

| 400 Bad Request           | Malformed GET request, e.g. parameters are missing. |

| 500 Internal Server Error | Other errors. |

*Content-Types*

| text/html | Webpage with user evaluatable content. E.g. error page, manual redirect, ... |

*Description*

The interface can be used to start the eID application.

The parameters ifdName, contextHandle, slotHandle and cardType address a particular eCard, or a type of card.

There are three meaningful combinations of the optional parameters:

* _none_

 Use the fist nPa available. Display a "Please insert nPa" dialog if needed. This is the behaviour of the AusweisApp.

* _cardType_

 Use the fist card of the specified type which is available. Display a "Please insert <cardType>" dialog if needed.

* _ifdName_, _contextHandle_, _slotHandle_

 Use exactly the card matching the parameters.

*Notes*

<pre>

TODO

* What happens if the Client Activator cannot start an application?

* What happens if the Client Activator cannot fetch a TC Token from the given TCTokenURL? Should that result in a 400 or 404?

</pre>

h2. GetStatus[1]

*URL*

@http://127.0.0.1:24727/getStatus@

*Method*

GET

*Query*

| session | The session parameter establishes an event queue for further requests with waitforChange. | Optional | 

*Returns*

| 200 OK                    | Status element (see below). |

| 500 Internal Server Error | Errors in the smartcard stack or the webserver. |

<pre>TODO: define Status element</pre>

*Content-Types*

| text/xml  | The Status element. |

| text/html | Error message in case of a 500 status code. |

*Description*

The interface can be used to request information about the eID application and its current state.

h2. WaitForChange

*URL*

@http://127.0.0.1:24727/waitForChange@

*Method*

GET

*Query*

| session | The session of a previously set up event queue (see [[Client_Activation#GetStatus|GetStatus]]). | Mandatory | 

*Returns*

| 200 OK                    | StatusChange element (see below). |

| 500 Internal Server Error | Errors in the smartcard stack or the webserver. |

<pre>TODO: define StatusChange element</pre>

*Content-Types*

| text/xml  | The StatusChange element. |

| text/html | Error message in case of a 500 status code. |

*Description*

The interface can be used to request status change information after an initial GetStatus call.

---

fn1. Openecard proposal: This parameter/interface is an Open eCard specific extension. It is not part of the official eCard specification.